Install & Compatibility
Where this runs
tested against v2.9.0 · 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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 13.0s · import 1.660s · 362MB
374MB installed
● package 374MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Universe
✓ from MDAnalysis import Universe
✗ import MDAnalysis as mda; u = mda.Universe(...)
This quickstart demonstrates how to create a simple MDAnalysis Universe object in memory, populate it with dummy atom data, select atoms, and perform a basic calculation. In a typical workflow, you would load data from actual structure (e.g., PDB) and trajectory (e.g., XTC, DCD) files using `mda.Universe('structure.pdb', 'trajectory.xtc')`.
import MDAnalysis as mda
import numpy as np
# Create an empty Universe to demonstrate basic operations without requiring files
# In real applications, you would load structure and trajectory files (e.g., PDB, XTC).
# u = mda.Universe("path/to/structure.pdb", "path/to/trajectory.xtc")
u = mda.Universe.empty(n_atoms=4, trajectory=True)
# Add dummy atom data to the empty Universe
u.add_atomgroup(mda.AtomGroup([u.select_atoms("all")[0]], universe=u, name='C'))
u.add_atomgroup(mda.AtomGroup([u.select_atoms("all")[1]], universe=u, name='H'))
u.add_atomgroup(mda.AtomGroup([u.select_atoms("all")[2]], universe=u, name='O'))
u.add_atomgroup(mda.AtomGroup([u.select_atoms("all")[3]], universe=u, name='N'))
u.atoms.types = ['C', 'H', 'O', 'N']
u.atoms.masses = [12.01, 1.008, 15.999, 14.007]
# Set dummy positions for a single frame
u.atoms.positions = np.array([
[0.0, 0.0, 0.0],
[1.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
[1.0, 1.0, 0.0]
])
print(f"Universe created with {u.atoms.n_atoms} atoms.")
print(f"First atom: {u.atoms[0].type} at {u.atoms[0].position}")
# Select atoms based on properties
carbon_atoms = u.select_atoms("type C")
print(f"\nSelected {carbon_atoms.n_atoms} carbon atom(s).")
print(f"Carbon atom position: {carbon_atoms.positions}")
# Calculate a simple property, e.g., center of mass
center_of_mass = u.atoms.center_of_mass()
print(f"\nCenter of mass of all atoms: {center_of_mass}")
Debug
Known issues
gotchaMDAnalysis maintains compatibility with a wide range of NumPy versions (e.g., 1.26.0 up to 2.0+ for MDAnalysis 2.10.0). However, using an MDAnalysis version that is too old with a very new NumPy (especially NumPy 2.0.0+) can lead to `AttributeError` or `TypeError` related to numerical types (e.g., `np.float` not found).fixUpgrade MDAnalysis to the latest version (2.8.0 or newer) to ensure full compatibility with NumPy 2.0+. If upgrading MDAnalysis is not possible, try pinning your NumPy version to a compatible range, typically `<2.0.0` for older MDAnalysis releases.
affects: <2.8.0 with NumPy >= 2.0.0
breakingThe minimum supported Python version for MDAnalysis has steadily increased across major releases. For instance, MDAnalysis 2.5.0 required Python >=3.9, while MDAnalysis 2.10.0 requires Python >=3.11. Installing on an older Python environment will fail.fixEnsure your Python environment meets or exceeds the minimum requirement for the desired MDAnalysis version. Check the official MDAnalysis documentation or PyPI page for the exact `requires_python` specification.
affects: All versions, as minimum Python requirement changes frequently.
breakingStarting with MDAnalysis 2.8.0, the core library license transitioned from GPLv3+ to LGPLv3+. While this primarily affects developers and projects linking against MDAnalysis, it's a significant change for users considering redistribution or integration into proprietary software.fixReview the LGPLv3+ license terms if you are developing software that links to MDAnalysis or redistributing MDAnalysis. Previous versions remain under GPLv3+.
affects: >=2.8.0
Upgrade
Version history
2.10.0latest on PyPI · released Oct 17, 2025
Audit
Dependencies
numpyrequiredCore numerical operations and array handling.
biopythonoptionalRequired for some sequence and structure analysis functionalities.
pytngoptionalOptional dependency for reading TNG trajectory files.