plumed2 master is a development branch, and the release branches are the supported ones

The branch layout is the first thing to get right

plumed2 is the development version of plumed 2, and the README spends its opening section on how to choose a branch, which tells you that getting this wrong is a common mistake.

Branches named v2.X correspond to release branches. The master branch may contain non tested features and is not expected to be used by non-developers, and it typically contains features that will be available on the next release. Tags named v2.XbY correspond to beta releases, to be used with care, and tags named v2.X.Y correspond to official releases, where the advice is to use the latest available.

The support table then makes the maintenance picture concrete. The master branch's first stable release is listed as 2026, expected. v2.10 had its first stable release in 2025 and is still supported. v2.9 first shipped in 2023 and is still supported. Everything from v2.8 back to v2.0 is marked not supported, with their first stable release years running from 2022 down to 2013. v2.3 and older do not even have a CI badge, marked Not available.

So the practical rule is: build from a v2.X branch, not from master, unless you are developing PLUMED itself. Two branches are currently supported, which is a short window, so the upgrade path from v2.9 to v2.10 is the move to plan.

There is also a warning about the other branches. The repository contains a number of other branches related to specific features, and the README asks you to contact the developers committing on those branches before basing your work there, since they might contain temporary work and might be rebased later. The example given is the testdoc branch, which is set up to push a test copy of the manual and is often force pushed.

For bug reports the routing is specific too. Problems on beta or official releases go to the plumed-users mailing list, with the exact version stated. Problems on master go to the plumed2-git mailing list, which is also the place for discussions about new features. Either way, provide the git hash, obtained with git rev-parse HEAD.

Building it is configure and make, with optional pieces that degrade quietly

The quick compilation instructions are four lines:

    ./configure --prefix=$HOME/opt
    make
    make doc # optional
    make test # optional

The build system is the older autoconf and GNU make combination rather than a modern one, and the top-level file listing shows why there is so much in the tree. There is a configure script and a configure.ac, a Makefile and a Makefile.conf.in template configuration makefile, a sourceme.sh.in template configuration script, and a stamp-h.in. The Makefile conditionally includes Makefile.conf once the configuration has been found, and that file is what configure generates.

The required software is short. GNU make, a C or C++ compiler with c++17 support required as of version 2.10, and a modern version of the patch command line tool. The patch requirement is a consequence of the patches/ directory, which holds patch scripts that are applied during the build, and it is the kind of dependency that catches people out on a minimal container image.

The suggested software list is where the interesting behaviour is. An MPI library to run parallel simulations, and it should be the same library used by your MD code, so that PLUMED and the simulation share a communicator. Optimized blas and lapack libraries, which are automatically replaced by an internal version if not available. VMD molfile plugins to read arbitrary file formats, also automatically replaced by an internal version supporting a few formats. The Zlib library to use compressed data files. Doxygen to build the user manual, which itself may need Latex for the PDF manual and Graphviz to show the class hierarchy in the developer manual.

That word automatically replaced, repeated twice, is the important one. A missing BLAS or a missing VMD plugin does not fail the build, it silently gives you a slower or less capable PLUMED. Since ./configure checks the libraries and enables them if available, the configure output is the place to check what you actually got.

The make doc and make test targets are marked optional in the quick instructions, and the extensive installation instructions live in the user documentation rather than in the README.

The regression test suite is part of the build, and it runs against the uninstalled binary

The Makefile has more targets than a simple library would need, and they describe a project with a serious test culture.

There is a lib target that delegates to src, an install and uninstall pair, and a test target that depends on src, with the comment that PLUMED is compiled before tests. There is a check target, with the comment that it performs tests using non-installed PLUMED, which it does by setting LD_LIBRARY_PATH and PLUMED_PREPEND_PATH to the freshly built src/lib directory before descending into the regtest subdirectory. There is a check_failed target that runs the same suite but only over the tests that failed, and an installcheck target that performs tests using the installed version of PLUMED instead.

The two environment variables are the mechanism that makes an uninstalled build testable. PLUMED_PREPEND_PATH points the library at the build tree's own lib directory so it loads the just-compiled plugins rather than any installed version, and the same variable is used with the bindir for the installcheck variant. The PLUMED_PROGRAM_NAME variable is set for installcheck as well.

The regtest/ directory holds the regression tests including reference results, and the test/ directory holds examples. So the reference outputs are committed, and a change that alters numerical output shows up as a diff rather than as a silent behaviour change. There is also a checkfail subdirectory target, which runs the failure-checking pass.

The root listing shows a CHANGES/ directory rather than a single changelog file, plus release.sh as the developer utility to publish releases, and the scripts/ directory of shell tools. The presence of a patches/ directory alongside regtest/ and astyle/ tells you the project formats its own source with a local version of astyle, configured through .astyle.options, and there is a .clang-format file and a ruff.toml for the Python parts, with pythonformatter.sh alongside.

A plugin architecture, and directories for many front ends

The top-level entries describe more than a single C++ library, and the plugins/ directory is the centre of the design.

PLUMED is built around plugins that attach to a running molecular dynamics simulation and bias it, or that analyse trajectories afterwards. The plugins/ directory holds them, and the src/ directory holds the core that loads them. The library is linked into the MD code, which is why the MPI requirement exists at all and why the plugin path has to be arranged so that the core and the plugins agree on it.

Around that core there are directories for a remarkable range of interfaces, which is the clearest sign of how widely this code is used. There is a python/ directory, a fortran/ directory, a json/ directory and a plugins/ directory, and the Makefile builds each of them as a SUBDIR alongside the source, the documentation and the regtest tree. There is a new-manual/ directory, a user-doc/ directory and a developer-doc/ directory, so the user manual and the developer manual are separate trees, and a vim/ directory where vim syntax files are generated.

The distribution side is present too. There is a docker/ directory where Docker is generated, a macports/ directory where Portfiles are generated, a conda/ directory, and a patches/ directory of patch scripts. The README's badges show the packaging reach: MacPorts, conda-forge, AUR, DPorts, FreeBSD and Spack all carry the project.

The configuration and build tooling reflect a mixed-language repository. The code is C++, but there is a Python subdirectory, a Fortran subdirectory, a Python formatter script and a ruff configuration file, and a .github-blame-ignore-revs file, which is the convention for marking commits that only reformat code so the history stays readable.

Where plumed2 is the wrong tool

The first wrong-tool case is a user who wants the newest features. The master branch is explicitly not expected to be used by non-developers, and its first stable release is listed as 2026 and expected. Building from master means running untested code, and the README's guidance to use the latest official release is not a formality for a numerical code where a subtle change can shift your results.

The second case is a user who cannot build C++. The source route needs a C++17 compiler, GNU make, patch and a working autoconf-style configure, and while the packaging badges show MacPorts, conda-forge, AUR, DPorts, FreeBSD and Spack, those all target specific platforms. If your environment is a locked HPC container with no package manager and no compiler, PLUMED is the wrong dependency, because the plugin architecture requires the library to be linked into the simulation code rather than bolted on afterwards.

The third case is a workload where PLUMED's design does not fit. PLUMED biases a running simulation or analyses a trajectory it was attached to. It is not a general trajectory converter, and its plugin set is aimed at enhanced sampling: free energy, metadynamics-style biasing and collective variables. The topic tags list enhanced-sampling, free-energy, molecular-dynamics, plugin and trajectory-analysis, which is the scope in one line.

For the alternative approach, the difference in approach is between a plugin-based tool and a standalone analysis script. If you already have a complete trajectory and want one number out of it, a post-hoc analysis script in Python is far less work than linking PLUMED into anything. PLUMED earns its complexity when you want to steer the simulation, because the bias is applied during the run and the free energy estimate depends on that. The other alternative is the molecular dynamics code's own built-in analysis, which is always an option and is always available without adding a dependency.

The one thing not to do is swap PLUMED for a plugin that reimplements a single collective variable. The value is in the whole plugin set and the shared bias infrastructure around it.

LGPL-3.0, frequent releases, and a licence that suits a linked library

The licence is LGPL v3, which is a deliberate fit for this kind of project. PLUMED is linked into someone else's molecular dynamics code and distributed as part of a simulation package, and the LGPL is the licence that lets the users of that package modify and redistribute the library while requiring that modifications to the library itself are published. The COPYING.LESSER file is in the root, matching the licence badge.

The release history is dense and current. The recent releases are v2.10.2 on 2026-10-19, v2.9.6 also on 2026-10-19, and v2.10.1 on 2026-07-01. That two lines on the same day is the maintenance branch and the release branch both receiving work, which is what you would expect from a project that supports two branches at once. The last push to the repository was on 2026-10-19.

The VERSION.txt file at the root holds the version, and the release.sh script is the developer utility to publish releases, with the actual tarball production handled by the makefile machinery and the macports/ Portfile generation kept in step.

The support window is the part to plan around. The table says v2.10 and v2.9 are still supported, and everything before v2.8 is not. A lab running production simulations needs to know which branch it is on and when the next one goes unsupported, because the migration from v2.9 to v2.10 is a real upgrade with a recompile and a revalidation of the results, not a package version bump.

The distribution channels are broad enough that most users should not compile from source at all. Conda-forge, MacPorts, the AUR, DPorts, the FreeBSD port and Spack all carry the project, and the Google group at plumed-users is the user support channel. The source build is the route for a plugin developer, for a platform none of those channels cover, or for matching the exact version your MD code expects.

Editorial conclusion

plumed2 suits a computational chemist or molecular dynamics developer who needs PLUMED plugins for metadynamics, biasing and trajectory analysis, and who can build from source with a C++17 compiler. It does not suit a user who wants the newest features, since the master branch is explicitly not expected to be used by non-developers. Before building, pick a supported release branch rather than master, check that the v2.10 branch matches your molecular dynamics code, and confirm the optional dependencies you need, since MPI, BLAS, LAPACK, VMD plugins and zlib are each detected and silently replaced by internal versions when absent.

Frequently asked questions

Official sources

1. License: LGPL-3.0
2. plumed/plumed2 on GitHub
3. Project website
4. README
5. Releases