Installing from source

Oliver Beckstein edited this page Nov 17, 2015 · 14 revisions

MDAnalysis is open source and you can always build and install the package from source. This gives you the flexibility to use either the latest releases or, if you like living on the cutting edge, you can also use the current development version of the code. This page contains notes on how to install from source.

For alternative ways to install MDAnalysis, see the page Install.

Installing from source

MDAnalysis is also distributed in source form. In order to build the library some C code needs to be compiled. Thus you will need

  • python (>=2.7 and <3)
  • a C compiler (GNU gcc works),
  • the Python header files (typically in a package python-dev),
  • numpy to compile the DCD reader and numerical extensions,

See Additional non-standard packages below for what else you need at run time.

The source code can be obtained via the Downloads page and as described below under Getting the source. The primary dependency is numpy.

Please read through this whole document. Installing MDAnalysis is unfortunately not always absolutely straightforward because of the various dependencies on other packages. InstallRecipes collects a number of examples of how MDAnalysis has been successfully installed on various systems; possibly one of the recipes applies to your situation, too, and you can simply copy and paste.

Getting the source

You can either get the source tar files or check out the source code from the git repository.

Source tar files

In order to download the source packages, you need to go to the PyPI repositories:

Git repository

Alternatively, you can check out the MDAnalysis directory from the git repository at In most cases simply do

git clone
cd mdanalysis

If you have cloned the repository before, all you need to do is

git pull

to update your files.

Standard installation from source

If you want to install MDAnalysis from source you will need a C compiler.

We recommend (for python >= 2.7) the following way of installing in your home directory (a so called "user" installation) ::

python build
python install --user

If you want to install in the system wide python directory you will probably require administrative privileges, and so do

sudo python install

It is also possible to use --prefix, --home, or --user options for to install in a different (probably your private) python directory hierarchy.

If you have problem at this stage then have a look at the operating system specific notes at the end of this file or look in the issue tracker --- maybe the problem is recognized and a workaround can be found in the comments

Unfortunately, installing python packages is not always completely straightforward, so please read through these docs and perhaps ask on the mailing list.

Selecting an installation directory

In you should be able to use

 python install --prefix LOCAL_DIRECTOY

or any of the other options of distutil's to install in alternative directories.

Please ask on the mailing list for help with installation and/or file a bug through the issue tracker.


One can also use pip. For all releases, you should be able to just do

pip --upgrade MDAnalysis 
pip --upgrade MDAnalysisTests

and pip will download the source distribution from the Python package index and install them, together with any required dependencies.

If you want to install from the checked out source, you can also use pip:

pip [options] ./mdanalysis

for a standard installation.

Developer installation

A developer installation (that immediately reflects changes to the sources) can be done with

cd ./mdanalysis
python setup develop [options]

For testing one can simply use

python develop --install-dir=$HOME/python-lib/ --script-dir=$HOME/bin

This builds and installs a working version in ~/python-lib/MDAnalysis which is linked to the unpacked source. Then add $HOME/python-lib to the PYTHONPATH

export PYTHONPATH=${PYTHONPATH}:$HOME/python-lib

However, the developer installation above is probably cleaner.

Additional non-standard packages

See the operating system specific notes below for hints how to get the necessary packages through the native package management system. Please add your own (e.g. for RPM based systems, which the developers are not using heavily).

  • python-dev includes Python.h, which is required for compiling.
  • numpy is used at the compilation stage to find maths libraries.
  • biopython is used for strict PDB file parsing and the KD-tree library
  • scipy, netcdf4-python are only needed when one wants to use all MDAnalysis functions but are not required for compiling.

Required python packages

In order to make full use of the library in your own python code you will need at least

  • numpy of version 1.5 or greater
  • scipy
  • matplotlib
  • BioPython
  • networkx --- for analysis of lipid leaflets via MDAnalysis.analysis.leaflet
  • GridDataFormats
  • netcdf4-python: If you want to operate on AMBER binary trajectories (NetCDF) then you will need to have working NetCDF support based on the netcdf4-python package.
    • If you get a ValueError: did not find HDF5 headers during installation then you should install the hdf5 development package through your package manager (see below for some hints on how to do this for Linux and Mac OS X).

Optional python packages

In order to run the UnitTests you will need

  • numpy >= 1.5
  • nose >= 1.3.7

OS specific notes

See also InstallRecipes for "copy & paste" installation instructions for various operating systems and versions.


  • Install prerequisite packages on Ubuntu or Debian with

    sudo apt-get install python-dev python-cython python-numpy g++
  • Install packages needed for full functionality

    sudo apt-get install python-scipy python-matplotlib python-biopython  libhdf5-dev 

    (If you have issues with the netcdf libraries see the wiki page on netcdf); the netcdf and libhdf5-dev packages are required if you want to be able to process AMBER netcdf (binary) trajectories.)

  • Tested with GNU compilers

Mac OS X

Mac Ports

Tested 10.6.8+MacPorts

port install  py27-numpy  py27-cython
port install  py27-scipy  py27-matplotlib py27-biopython hdf5 netcdf+dap+netcdf4

(The netcdf and libhdf5-dev packages are only required if you want to be able to process AMBER netcdf (binary) trajectories.)

Other packages such as networkx and GridDataFormats are automagically installed when running python install (or pip).


Tested with Mac OS X 10.4.11+fink (has not been tested since 2011 — feedback is welcome)

Install prerequisite packages using fink

     fink install cython-py25 scipy-core-py25 scipy-py25

Install packages needed for full functionality

     fink install  matplotlib-py25 biopython-py25

NOTE: Use the Apple-provided gcc, not the fink provided one. Apparently, only Apple's gcc has the -arch flag that appears to be required for python install. (Thanks to Justin Lemkul for pointing it out; see Issues after Installation). In order to install Apple's gcc you will need to install the Apple Developer Tools that come on one of the additional installation disks with the Mac or install Xcode from the web (note that Xcode 3.x is free and can be obtained by registering online for the Apple Developer Connection).

Older versions

The installation procedure for older versions of MDAnalysis is chronicled under Installation from Source: Historical notes on older versions but is unlikely to be relevant for current users.

Project Information

GNU GPL v2 code license
Labels: python, molecular dynamics, analysis, DCD, CHARMM, LAMMPS, NAMD, Gromacs, computer simulation, atoms, coordinates, trajectory, XTC, Library, object-oriented
Core Developers


Release Notes
Guide for Developers
Google Summer of Code

Code of Conduct


@mdanalysis on Twitter
Downloads (PyPi)
Mailing Lists:
User discussion group
Developer mailing list

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.