MDTraj: reading and analysing molecular dynamics trajectories

One reader for the many formats simulation packages write

MDTraj is a Python library that lets users manipulate molecular dynamics trajectories and perform a variety of analyses, including fast RMSD, solvent accessible surface area and hydrogen bonding. The feature the project highlights first is not an analysis but a format: the wide variety of molecular dynamics trajectory file formats which are supported, including RCSB pdb, GROMACS xtc and trr, CHARMM and NAMD dcd, AMBER NetCDF, AMBER mdcrd, TINKER arc and MDTraj HDF5. The feature list puts it more bluntly, reading and writing from every MD format imaginable, with pdb, xtc, trr, dcd, netcdf, mdcrd, prmtop and gsd named as examples.

That is the problem it solves. A simulation produces a trajectory, and the analysis you want to run lives in a different tool from the one that produced the file. GROMACS writes xtc, NAMD writes dcd, AMBER writes NetCDF or mdcrd, and a script that reads one of them will not read the others without either a converter or a second library. MDTraj removes the branch by making the format an argument to the loader rather than a property of your code.

The promise in the readme is that you can read, write and analyse MD trajectories with only a few lines of Python code, and the stated design is a lightweight API with a focus on speed and vectorised operations. The audience is researchers and engineers doing post-processing on simulation output, in fields the project classifiers name as bio-informatics and chemistry.

Fast RMSD, and what the speed claim rests on

The performance claim in the readme is specific: blazingly fast RMSD calculations, described as 4x the speed of the original Theobald QCP. RMSD, root mean square deviation, is the standard measure of how far a structure has moved from a reference, and it is the most common quantity computed over an entire trajectory, which is why it dominates the runtime of a typical analysis script.

The comparison target is worth noting. Theobald's QCP is itself the fast quaternion-based algorithm that replaced the older mass-weighted coordinate superposition, so being four times faster than it is a claim about a well optimised baseline, not about a naive one. The examples directory includes rmsd-benchmark.ipynb and rmsd-drift.ipynb, which are the notebooks where such a comparison would live, so the claim is at least reproducible in principle from the repository.

The mechanism behind the speed is visible in the packaging. MDTraj is not pure Python. The build requires cython at version 3 or newer alongside numpy, and the compiled extension modules are declared in setup.py as Extension objects pulling in C sources together with Cython .pyx files. The XTC reader is one such extension, built from the xdrfile C sources and an xdrfile_xtc.pyx wrapper.

The vectorisation claim is the other half, and it is a design constraint rather than a trick. An RMSD loop in Python over millions of frames will be slow whatever the algorithm, so the API is built around numpy arrays and operations that run over whole trajectories at once.

The compiled format readers are built from C and Cython

The setup.py is worth reading, because it tells you what you are installing and what a source build requires. The build machinery is factored out into a basesetup.py that provides a CompilerDetection class, a StaticLibrary class, a build_ext function and a parse_setuppy_commands helper, and the extension modules are declared by a format_extensions function.

The XTC extension declaration shows the pattern clearly:

    xtc = Extension(
        "mdtraj.formats.xtc",
        sources=[
            "mdtraj/formats/xtc/src/xdrfile.c",
            "mdtraj/formats/xtc/src/xdr_seek.c",
            "mdtraj/formats/xtc/src/xdrfile_xtc.c",
            "mdtraj/formats/xtc/xtc.pyx",
        ],

Each format reader is its own extension module, with the C implementation of the file format, in this case the xdrfile library, alongside a thin Cython wrapper.

Two details in the build are practical rather than incidental. There is an optional --disable-openmp switch, and the setup script removes it from sys.argv to detect whether it was passed, which means OpenMP is on by default and you can turn it off at configure time if your build environment cannot handle it. On Windows, two extra native libraries are linked, Ws2_32 for the socket functions and Shlwapi, with the latter needed for path handling in the dtr reader.

The practical consequence is that installing MDTraj from source needs a working C compiler and Cython, and that a prebuilt wheel is by far the easier route.

Install routes, Python floor and the packaging spec

MDTraj is distributed on PyPI and on conda-forge, and both are advertised in the readme through badges for the PyPI version, the Anaconda Server version and the Anaconda Server downloads, so either route is a first class option. The documentation is hosted at mdtraj.readthedocs.io, and the project homepage is mdtraj.org.

The version constraint is the first thing to check. The pyproject.toml declares requires-python = ">=3.12", and the classifiers list Python 3.12, 3.13, 3.14 and 3.15, with the Python 3 only marker and the C classifier alongside Python. If you are on an older interpreter this is a hard stop, and it also means MDTraj no longer supports the older interpreters that many institutional environments still run.

The runtime dependencies are small: numpy~=2.0, packaging, pyparsing with the 3.3.3 release excluded, and scipy. The optional extras cover the formats and data structures you may not need, with netcdf4, networkx, pandas, pyarrow and tables in the optional group, pytest, pytest-recording, pytest-rerunfailures and pytest-xdist in the tests group, and an all group that combines both. The version is not hardcoded in pyproject.toml, which lists it as dynamic, because the project uses versioneer to derive it from the repository.

The project also carries a SPEC 0 badge, the Minimum Supported Dependencies specification from the scientific Python community, which signals a commitment to keeping the dependency floor current rather than pinning users to old versions of numpy or scipy.

The analysis functions and what the examples folder covers

The feature list names the analysis surface: bonds, angles and dihedrals, hydrogen bonding identification, secondary structure assignment, and NMR observables. The project topics add dihedral angles, pdb files and rmsd, which is a fair summary of what people actually use it for.

The examples directory is the best catalogue of the intended workflows, and the notebook names describe them without needing the documentation. There is a notebook for secondary structure, one for hydrogen bonds, one for native contacts, one for pi stacking, one for NMR, one for principal components, one for atom selection, one for centroids, one for clustering and one for two-pass clustering, plus a ramachandran-plot notebook and a solvent-accessible-surface-area notebook. Two are about the data rather than the science: iterload.ipynb, about loading a trajectory incrementally, and simulation-with-openmm.ipynb, about driving an OpenMM simulation from Python.

That iterload notebook points at a real property of the domain. A production trajectory can be tens of gigabytes, and a library that insists on holding the whole thing in memory is unusable for long runs. The lightweight, vectorised API and the ability to work in slices are not stylistic preferences here, they are what make the library usable on production data.

A caution about scope. MDTraj analyses trajectories, it does not produce them. The OpenMM notebook is a convenience for testing an analysis against a simulation you can generate, not a claim that MDTraj is a simulation package.

Licence, maintenance and the citation requirement

MDTraj is licensed under GNU LGPL version 2.1, or at your option a later version of the license, which the project spells out as LGPL-2.1-OR-later in the pyproject metadata with the licence files collected by a glob pattern. There is a wrinkle the readme flags: various sub-portions of this library may be independently distributed under different licenses, and those files carry their specific terms. In practice that means the LGPL covers the library as a whole, but a vendored or adapted piece inside it may carry its own conditions, so a distribution audit means reading the licence files rather than the headline.

The project status section says MDTraj is actively maintained by community members and representatives from Folding@Home, The Molecular Sciences Software Institute, and the Open Force Field Initiative. The last push to the repository was on 2026-10-14, and the release history is steady, with 1.11.2 on 2026-10-05, 1.11.1.post2 on 2026-07-08 and 1.11.1.post1 on 2026-01-26.

The citation request is the part researchers care about. The readme states that MDTraj is research software and that if you make use of it in scientific publications you should cite it, and gives the BibTeX entry for the Biophysical Journal paper, with the DOI 10.1016/j.bpj.2015.08.015. That is the project's own request rather than a legal obligation, but it matters for anyone using it in published work.

The project also asks for a DOI for citing, and directs feature ideas and general questions to the repository discussions rather than the issue tracker, with the issue tracker reserved for contributions and bug reports.

Editorial conclusion

Adopt MDTraj if your analysis code has to read trajectories written by more than one simulation package, since the format coverage is the reason it exists, and if the trajectory files are large enough that a vectorised RMSD matters. Do not adopt it if your work is a single protein on a single format with a well tested analysis tool already in your pipeline, since MDTraj is an analysis library rather than a simulation engine and it will not replace the code that produced the trajectory. Before you install, check your Python version against the requires-python of 3.12 or above, and plan for a C toolchain, because the compiled extension modules for the format readers are built from C and Cython sources and are not shipped as pure Python.

Frequently asked questions

Official sources

1. License: LGPL-2.1
2. mdtraj/mdtraj on GitHub
3. Project website
4. README
5. Releases