Install & Compatibility
Where this runs
tested against v1.10.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 8.2s
py 3.11
✕ build_error
✓ 7.38s
py 3.12
✕ build_error
✓ 7.55s
py 3.13
✕ build_error
✓ 7.83s
py 3.9
✕ build_error
✕ build_error
265MB installed
● package 265MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mdtraj
✓ import mdtraj as md
The convention is to import mdtraj as 'md'.
Trajectory
✓ import mdtraj as md
traj = md.Trajectory(...)
This quickstart demonstrates loading a minimal PDB file into an MDTraj Trajectory object, inspecting its basic properties, and performing a simple distance calculation. It cleans up the temporary file afterward.
import mdtraj as md
import os
# Create a minimal PDB file for demonstration
pdb_content = """
ATOM 1 N ALA A 1 1.000 2.000 3.000 1.00 10.00 N
ATOM 2 CA ALA A 1 2.000 2.000 3.000 1.00 10.00 C
ATOM 3 C ALA A 1 3.000 2.000 3.000 1.00 10.00 C
TER
"""
pdb_filename = "minimal.pdb"
with open(pdb_filename, "w") as f:
f.write(pdb_content)
# Load a trajectory
traj = md.load(pdb_filename)
print(f"Trajectory loaded: {traj.n_frames} frames, {traj.n_atoms} atoms.")
print(f"Topology has {traj.n_residues} residues.")
# Example calculation: compute distance between atoms 1 and 2 (CA and C)
# Indices are 0-based
distances = md.compute_distances(traj, [[1, 2]])
print(f"Distance between atom 1 and 2: {distances[0][0]:.3f} nm")
# Clean up the dummy file
os.remove(pdb_filename)
mdtraj --version
Debug
Known issues
gotchaMDTraj uses nanometers (nm) for length and picoseconds (ps) for time as its internal default units. Many other MD packages or traditional practices use Angstroms (Å) or different time units, which can lead to unit conversion errors if not explicitly handled.fixAlways be aware of the units used by MDTraj functions. Convert units explicitly when interacting with other software, e.g., multiply Å by 0.1 to get nm, or divide nm by 0.1 to get Å.
affects: All versions
gotchaMDTraj's atom selection syntax, while powerful, is unique and not identical to selection languages in other MD programs (e.g., VMD, Amber). Misunderstanding the syntax is a frequent source of incorrect selections or empty results.fixConsult the MDTraj documentation's 'Atom Selection' guide (mdtraj.org/latest/atom_selection.html). Test selections on small topologies or use `traj.atom_slice(traj.topology.select('...'))` to inspect results. affects: All versions
gotchaLoading very large trajectories (many frames, many atoms) entirely into memory using `md.load()` can quickly exhaust available RAM, leading to `MemoryError`.fixFor large files, use `md.iterload()` to iterate over frames without loading the entire trajectory at once. Alternatively, use `md.load(..., stride=N)` to load only a subset of frames, or `md.load(..., atom_indices=atom_selection)` to load a subset of atoms.
affects: All versions
breakingSpecific file formats (e.g., HDF5, NetCDF, DCD) rely on external Python packages (like `h5py`, `netCDF4`). Updates to these underlying packages or `mdtraj` itself can sometimes introduce breaking changes or require specific versions for proper functionality.fixIf encountering read/write errors for specific formats, ensure `mdtraj` and its relevant dependencies (e.g., `pip install h5py netCDF4`) are up-to-date and compatible. Consult `mdtraj`'s release notes for specific version requirements.
affects: Versions 1.9.x to 1.10.x, 1.10.x to 1.11.x, and future major updates.
Errors
Common errors & fixes
MemoryError: Unable to allocate ... / numpy.core._exceptions._ArrayMemoryError: Unable to allocate ...
Attempting to load a trajectory that is too large to fit into available RAM.
fixFor large trajectories, use `md.iterload()` to process frames iteratively, or `md.load(..., stride=N)` to load only a subset of frames, or `md.load(..., atom_indices=...)` to load a subset of atoms.
AttributeError: 'Trajectory' object has no attribute 'x'
Users accustomed to other MD libraries might expect direct access to coordinates via `traj.x`, `traj.y`, `traj.z`.
fixMDTraj stores coordinates in `traj.xyz` as a NumPy array of shape (n_frames, n_atoms, 3). Access the full coordinate array via `traj.xyz`.
TypeError: expected an input topology
Some MDTraj functions require a complete `Topology` object that defines bonds, angles, and dihedrals, not just atomic coordinates. This often occurs when loading simple PDBs without explicit bond records or using a trajectory without a complete topology.
fixEnsure your trajectory has a complete topology. Load from a format that contains bond information (e.g., Amber topology files, GROMACS topologies, or more complex PDBs), or use `traj.guess_bonds()` to infer bond connectivity after loading.
ValueError: No atoms selected by '...' (where '...' is your selection string)
The atom selection string provided to `traj.topology.select()` or similar functions did not match any atoms in the trajectory's topology. This can be due to typos, incorrect atom/residue names, or misunderstanding the selection syntax.
fixDouble-check the selection string against the MDTraj documentation's 'Atom Selection' guide. Verify atom and residue names present in your topology by printing `traj.topology` or iterating through `traj.topology.atoms`.
Upgrade
Version history
1.11.1.post1latest on PyPI · released Jan 26, 2026
Audit
Dependencies
numpyrequiredCore numerical computations and array handling.
scipyrequiredScientific computing utilities, often used for advanced analysis.
cythonrequiredUsed for performance-critical compiled extensions.
msgpackrequiredUsed for efficient serialization and deserialization of data.
h5pyrequiredRequired for HDF5 file format support (e.g., TRR, XTC, own HDF5 format).
packagingrequiredFor robust version comparisons and dependency management.