In order to properly install this package, you need a version of python that plays well with libraries like numpy and matplotlib. This is easy or less easy depending on your operating system, but we have a brief walk through at Obtaining a Python Distribution.

Terminal terminology

Commands below that begin with $ must be run from the terminal containing your preferred python distribution, neglecting the $. Depending on operating system, this could be the normal terminal, or a modified prompt. See Obtaining a Python Distribution for more information if you are not sure.

Commands that begin with >>> should be run inside of a python environment. The following would be a valid set of instructions to pass to your terminal, printing a very basic python command:

$ python -m "print('hello world')"
hello world
$ python
>>> print('hello world')
hello world

Installing from pip

pip is the easiest way to install the latest version of serpentTools. First, ensure that you have numpy installed, as this is one of the required packages that is tricky to install. You can check by opening up a your preferred terminal and executing

$ python -c "import numpy"

If this fails, please consult Obtaining a Python Distribution.

Next, installation with pip can be completed with:

$ python -m pip install --user --upgrade pip serpentTools

This installs the dependencies of the package, the latest serpentTools release, and upgrades your version of pip along the way. When a new release is issued, run the command again to install the updated version.

If you wish to install the development branch to get the latest updates as they happen, use the following command:

$ python -m pip install -e git+


Changes to the development branch may not always be back-compatible and may cause non-ideal outcomes. Be sure to check the Changelog before/after updating from the develop branch

See also pip install from git

Installing from a Release

  1. Download the source code for the latest release from GitHub releases as a .zip or .tar.gz compressed file.

  2. Extract/decompress the contents somewhere convenient and memorable

  3. Open your terminal and navigate to this directory:

    $ cd path/to/release
  4. Install using our setup script:

    $ python install
  5. Verify the install by running our test suite:

    $ python test

Installing via git

The newest features are available on the develop branch before getting pushed to the master branch. We try to give decent notice when features are going to change via warning messages and our Changelog, but changes to the API and other functionality can occur across the develop branch.

  1. Clone the repository and checkout the branch of your choosing. The default is develop:

    $ git clone
    $ cd serpent-tools
    $ git checkout master
  2. Install using our setup script:

    $ python install
  3. Verify the install by running our test suite:

    $ python test

Obtaining a Python Distribution

Obtaining a version of python into which serpent-tools can be installed varies by operating system, with Windows requiring the most finesse.

Linux/Mac/Unix-like Operating Systems

If you don’t have numpy installed, you will have to obtain it from your package manager or from pip:

# ubuntu
$ sudo apt-get install python-numpy
# pip
$ sudo pip install --upgrade numpy

If you already have numpy, then the pip installtion process will take care of our other dependencies.


The easiest and most painless way to obtain packages like numpy on Windows is with either the Anaconda or Miniconda distributions. Each of these also includes the Anaconda Prompt which is a modified terminal that plays better with Python. The former comes with a few hundred packages, included most of the ones needed for this project, bundled for you. The latter is a very small distribution and requires you to install the packages you want via conda. Should you choose this route, then you need to launch the Anaconda Prompt and install with:

$ conda install setuptools numpy matplotlib pyyaml

This prompt is what you should use when following the instructions in in Installation.