Installation Guide

The latest version of MDAnalysis can be installed using mamba/conda (recommended), or pip. If you need to install MDAnalysis from source, follow Install from source for stable releases. If you are a contributor or developer working on MDAnalysis, follow the Install for development for editable installation and code modifications.

Currently, the mamba/conda installs a version of MDAnalysis that does not include OpenMP acceleration due to limitations in precompiled conda packages. If you need OpenMP-enabled features, consider installing via pip and compiling from source with a compatible compiler and OpenMP support.

MDAnalysisTests is optional and is a separate test suite used for verifying MDAnalysis installations and running User Guide examples. It is not required for daily use, but some tutorials rely on it. The package is approximately 90 MB and is not updated frequently. If you plan to use tutorial examples or contribute to MDAnalysis, installing it is recommended.

MDAnalysis supports specific Python versions. For the latest supported versions, please refer to the CHANGELOG or the PyPI. Ensure you have a compatible Python version installed before proceeding.

Note

MDAnalysis supports Linux, macOS, and Windows.

mamba/conda

For most users, mamba is the recommended way to install MDAnalysis. It is a faster drop-in replacement for conda and efficiently handles dependencies. We also recommend creating a new environment for MDAnalysis to ensure a clean and isolated installation.

MDAnalysis supports two common ways to install with mamba:

1. Recommended: Use Mambaforge

Mambaforge is a minimal conda distribution that includes mamba by default, uses the conda-forge channel (preferred for MDAnalysis) and avoids clutter from Anaconda base packages.

To install MDAnalysis with Mambaforge, follow the mambaforge installation instructions and then run the following commands to install MDAnalysis:

mamba create -n mdanalysis -c conda-forge mdanalysis
mamba activate mdanalysis

To install the test suite (optional, ~90 MB):

mamba install -c conda-forge MDAnalysisTests

To upgrade, use:

mamba update mdanalysis

If you’re using MDAnalysis in JupyterLab, install ipywidgets for progress bar support:

mamba install -c conda-forge ipywidgets

2. Alternative: Use conda with conda-forge

If you prefer using conda directly (e.g., installed via Anaconda installer), create a new environment with packages from the conda-forge channel:

conda create -n mdanalysis -c conda-forge mdanalysis
conda activate mdanalysis

To install optional packages:

conda install -c conda-forge MDAnalysisTests ipywidgets

pip

The following command will install or upgrade the latest stable version of MDAnalysis via pip with core dependencies. This means that some packages required by specific analysis modules will not be installed.

pip install --upgrade MDAnalysis

MDAnalysis offers several optional dependency groups (“extra tags”) that you can install with pip to enable additional features:

  • analysis: optional dependencies for various analysis modules.

  • extra_formats: support for additional file formats.

  • parallel: install dask to enable parallel analysis across multiple cores or machines.

  • doc: install documentation build dependencies (e.g. Sphinx, themes).

To see the full list of available extras, check the pyproject.toml file.

To install with optional features, use pip with one or more extras:

pip install --upgrade MDAnalysis[analysis,extra_formats,parallel]

To install or upgrade the test suite (optional, ~90 MB):

pip install --upgrade MDAnalysisTests

If you’re using MDAnalysis in JupyterLab, install ipywidgets for progress bar support:

pip install ipywidgets

Install from source

This section is for users who want to install a specific stable version of MDAnalysis (e.g., for reproducibility or to debug a release). This is not intended for development or code contributions. If you’re a developer, see Install for development.

To install from source, you must first ensure that your environment already contains all necessary dependencies. We recommend you check the Creating a development environment to set up a clean development environment with all required dependencies. We recommend using mamba or conda to manage this setup.

Follow the steps in:

MDAnalysis uses different Git branches for different purposes:

  • package-X.Y.Z: These are tags, not branches, and represent stable release versions (e.g., package-2.9.0). These tags are ideal if you need reproducibility, debugging, or version locking. You can browse all tags on the GitHub Branches page.

  • develop: The develop branch is the default and active development branch. If you’re contributing to MDAnalysis or want the latest unreleased features, base your work on this branch (see Install for development).

Clone the repository and check out the tag corresponding to the desired version:

git clone https://github.com/MDAnalysis/mdanalysis
cd mdanalysis
git checkout package-<version>

You will now be in a detached HEAD state, which is expected when checking out a tag. This allows you to explore or install that version without affecting branches. If you plan to make changes, you can create a new branch based on the tag:

git switch -c my-fix-based-on-2.9.0

To install MDAnalysis from this version:

pip install package/.

To run tests:

pip install MDAnalysisTests

Install for development

This section is for contributors and developers who want to modify MDAnalysis or contribute to its development. You’ll install MDAnalysis in editable mode, which allows you to make code changes without reinstalling the package each time.

Before installing, follow the steps described in the Install from source to set up a clean environment with all dependencies.

Once your environment is ready, install MDAnalysis in editable mode:

git clone https://github.com/MDAnalysis/mdanalysis
cd mdanalysis
git switch develop    # work on the develop branch
git checkout -b my-feature-branch  # Create a new branch for your changes
pip install -e package/

Installing in editable mode (-e) means that any changes you make to the MDAnalysis source code are immediately available without needing to reinstall.

If you plan to run tests you can install the test suite:

# Install the test suite (optional but recommended for contributors)
pip install -e testsuite/

For more on how to set up and contribute, refer to the Contributing to MDAnalysis guide.

Testing

The tests rely on the pytest and numpy packages, which must also be installed. Run tests with:

pytest --disable-pytest-warnings --pyargs MDAnalysisTests

All tests should pass (i.e. no FAIL, ERROR); SKIPPED or XFAIL are ok. If anything fails or gives an error, ask on GitHub Discussions or raise an issue.

Running MDAnalysis tests can take some time, as there are many test cases. The plugin pytest-xdist can be used to run tests in parallel.

pip install pytest-xdist
pytest --disable-pytest-warnings --pyargs MDAnalysisTests --numprocesses 4

Custom compiler flags and optimised installations

You can pass any additional compiler flags for the C/C++ compiler using the extra_cflags variable in setup.cfg. This allows you to add any additional compiler options required for your architecture.

For example, extra_cflags can be used to tune your MDAnalysis installation for your current architecture using the -march, -mtune, -mcpu and related compiler flags. The optimal compiler flags depend on your CPU architecture. Commonly recommended settings are:

- #extra_cflags =
+ extra_cflags = -march=native -mtune=native

Use of these flags can give a significant performance boost where the compiler can effectively autovectorise.

Be sure to use the recommended flags for your target architecture. In many cases, -march and -mcpu can be used together or separately, and their behavior depends on your platform and compiler version. For example, ARM platforms often prefer -mcpu, while PowerPC may use both -mcpu and -mtune. Refer to the GCC documentation on -march and -mcpu for platform-specific guidance.

Full discussion of these flags is available elsewhere (such as here in this wiki or in this ARM blog post) and a list of supported options should be provided by your compiler. The list for GCC is provided here.

Warning

These compiler options are advanced and may reduce binary compatibility. In particular, using -march may restrict MDAnalysis to the exact CPU architecture it was compiled on. We strongly recommend that you run the test suite on your intended platform before proceeding with analysis.

In cases where you might encounter multiple CPU architectures (e.g. on a supercomputer where the login node and compute node have different architectures), you should avoid changing these options unless you are experienced with compiling software in these situations.

Additional datasets

MDAnalysisData is an additional package with datasets that can be used in example tutorials. You can install it with mamba / conda or pip:

# conda
conda install -c conda-forge mdanalysisdata
# pip
pip install --upgrade MDAnalysisData

This installation does not download all the datasets; instead, the datasets are cached when they are first downloaded using a Python command.