Pynbody Installation

Nothing makes us happier than a new pynbody user, so we hope that your installation experience is swift and painless. If you encounter issues during the installation process, please let us know right away. Once you complete the installation, don’t forget to read the Seeking Further Assistance section. Finally, if you decide you like pynbody and you end up using it for your scientific work, please see Acknowledging Pynbody in Scientific Publications. Enjoy!

In brief

To install the latest release version (which depends only on numpy and scipy), use

pip install pynbody

To install from our bleeding edge, use

pip install git+git://

If you have problems or need more help, read on.

Getting python

If you’re new to python we recommend using the Anaconda Python bundle from Continuum Analytics that comes with a nice and easy to use package manager conda. They provide free licenses for academic use, and the default installation includes all the pakages you require.

As of 2020, Python 2.X is no longer supported <> by the Python developers or by core modules such as numpy. For this reason, we have also removed support from pynbody.

If you desparately want to continue using Python 2.7, you can use pip to install old versions of pynbody, but these are provided without support.

Installing pynbody direct from the repository

You can type in your shell:

pip install git+git://

and everything should happen automatically. This will give you whatever the latest code from the git repository.


If your distutils are not installed properly and you don’t have root permissions, this will fail – see distutils.

If you don’t have pip or if you want to develop pynbody here is how you can do it manually.

First, clone the git repository from Github. Pynbody uses git for development:

  1. git is probably already on your machine – try typing git from the shell. If it exists, go to step 2.

  2. get the appropriate binary from and install git

  3. $ git clone

  4. to get the newest from the repository, run git pull.

  5. $ cd pynbody

  6. $ pip install .[all]

Now the package is installed wherever your python packages reside and should be importable from within python:

  1. $ cd ~

  2. $ python

  3. >>> import pynbody

If this yields no errors, you are done!


If you plan on joining the development efforts and you are unfamiliar with git, we recommend that you spend some time getting familiar with it. The git documentation is quite good and it’s worth a read through Chapter 3 on branching. You may also choose to fork the repo if you already have a github account.

Upgrading your installation and testing features or bug-fixes

If you want to use the most recent version from the repository because a crucial bug has just been fixed, for example, you can easily update your installation. If you installed using pip to begin with, simply do

pip install -I --no-deps git+git://

If you cloned or forked the git repository and installed manually, go into the top-level pynbody source directory (the one with in it) and do :

git checkout master  # make sure you are on the master branch
git pull origin master
pip install .

If you are testing a new feature or a bug fix that resides in a branch other than master this procedure is slightly different:

git fetch
git checkout -b branch origin/branch  # where "branch" will be the name of the branch for bug fix or feature
pip install .

When you install a new version of the code and you already have a python session active with pynbody loaded, you have to (carefully) reload all of the affected pynbody modules. The safest is to just quit and restart the python session if you’re not sure.

Open your simulation and start analyzing

Check out the rest of the tutorials section and especially the A walk through pynbody’s low-level facilities to get going.

Updating Code

Remember that the master branch is the code that everyone else receives when they do a fresh clone of the repository. It is therefore recommended that any development work is done in a separate branch that is merged back into the main branch only when it has been satisfactorily checked. See What a Branch Is and a primer on Basic Branching and Merging in the git documentation. This description of a workflow that discusses tidying up development branches before merging into the master branch is a good read.

We are in pretty active development stage at the moment, so it’s always a good idea to keep your code updated. If you want to see what everyone else has been commiting, you can see the commit history on the github code site.

Nose tests

The root directory of the pynbody distribution includes a nose directory, where the unit (nose) tests reside. In order to run them, you’ll need to download the testdata bundle from the downloads section of the pynbody site.

Building your own documentation

You obviously know where to find the documentation since you are reading it. But if you wanted to build your own flavor of it or if you want to contribute to the documentation, go to docs in the root directory. You will need to install Sphinx to build the docs, and this is usually most easily done with easy_install sphinx if you have distutils properly configured. Once you have sphinx installed, you can simply run make html in the docs directory to build the html version or make latexpdf to generate a pdf file, for example. All builds are found in _build.