Installation

Installation#

There are three options for installing msprime:

Via Conda: the recommended options for most users
Via Pip: more flexibility and control for advanced users
Via Container: to use msprime inside an extremely isolated environment

Via Conda#

Convenient conda packages are available for Python 3.7+ on Linux, OSX and Windows. These pre-built binary packages are built using conda-forge.

Quick Start#

Install conda using miniconda. Make sure you follow the instructions to fully activate your conda installation!
Set up the conda-forge channel using conda config --add channels conda-forge.
Create a conda environment and install msprime into it: conda create -n msprime-env msprime
Activate the environment: conda activate msprime-env
Try out msprime: msp --version.

Warning

Always use an environment when installing conda packages as installing can lead to many difficult to debug issues.

There are several different ways to obtain conda. Please see the anaconda installation documentation for full details.

Full example#

In this example we create a conda environment and install msprime into it on an OSX machine. We assume that conda has been installed and bash shell is being used (Windows users will need to modify the commands slightly).

$ conda create --name msprime-env
...

  environment location: /home/jean/miniconda3/envs/msprime-env

Proceed ([y]/n)? y

Preparing transaction: ...working... done
Verifying transaction: ...working... done
Executing transaction: ...working... done
#
# To activate this environment, use
#
#     $ conda activate msprime-env
#
# To deactivate an active environment, use
#
#     $ conda deactivate

$ conda activate msprime-env
(msprime-env) $ conda install -c conda-forge msprime
...

  added / updated specs:
    - msprime

The following NEW packages will be INSTALLED:
...

Proceed ([y]/n)? y

Downloading and Extracting Packages

Preparing transaction: ...working... done
Verifying transaction: ...working... done
Executing transaction: ...working... done

(msprime-env) $ python
Python 3.8.5
[GCC 7.3.0] :: Anaconda, Inc. on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import msprime
>>> ts = msprime.sim_ancestry(3)
>>> print(ts.draw_text())
3.18┊      10     ┊
    ┊    ┏━━┻━━┓  ┊
2.08┊    9     ┃  ┊
    ┊  ┏━┻━┓   ┃  ┊
0.80┊  ┃   ┃   8  ┊
    ┊  ┃   ┃  ┏┻┓ ┊
0.42┊  ┃   7  ┃ ┃ ┊
    ┊  ┃  ┏┻┓ ┃ ┃ ┊
0.34┊  6  ┃ ┃ ┃ ┃ ┊
    ┊ ┏┻┓ ┃ ┃ ┃ ┃ ┊
0.00┊ 0 4 1 3 2 5 ┊
  0.00          1.00

Please see the conda documentation for more details on managing packages and environments.

Via Pip#

Installing using pip is more flexible than conda as it can support more versions of Python and dependencies can be customised.

Warning

If you installed Python using anaconda/miniconda, please install msprime using conda. Link/load time errors will occur if you mix a conda installed Python with system libraries.

To install msprime via pip, first check system requirements, then run pip install.

check system requirements#

Msprime requires Python 3.7+ and pip. Run

$ python3 -m pip --version

to make sure you see Python 3.7 or greater. If you do not, do installation via conda.

On most platforms, pip will install msprime pre-built binaries without any additional requirements. Follow pip install from source to install from sources instead pre-built binaries.

run pip install#

We can install msprime easily using pip:

$ python3 -m pip install msprime

(It is generally better to use python3 -m pip rather than call pip directly since this allows you to control which installation of Python the package is installed to.)

If you do not have root access to your machine, you can install msprime into your local Python installation as follows:

$ python3 -m pip install msprime --user

To use the mspms program you must ensure that the ~/.local/bin directory is in your PATH, or simply run it using:

$ ~/.local/bin/mspms

To uninstall msprime, simply run:

$ python3 -m pip uninstall msprime

pip install from source#

Install from source if run pip install fails or you do not want to use pre-built binaries.

There may be additional requirements depending on the specific platform. In particular, installation of GNU Scientific Library (GSL) is sometimes needed:

Debian/Ubuntu#

$ apt-get install python-dev libgsl0-dev

Redhat/Fedora#

$ yum install gsl-devel

FreeBSD#

$ pkg install gsl

OS X#

We recommend using Via Conda to install msprime on OS X. However, it is also possible to install using Homebrew:

$ brew update
$ brew install gsl

Windows#

Use Via Conda, do not install via pip on Windows.

With GSL installed, install from source by doing:

python3 -m pip install msprime --no-binary msprime

Via Container#

An open container image (aka docker image) is built on Dockerhub for each release of msprime. Each image is tagged with the corresponding release. For example, for msprime release 0.7.5, the corresponding image tag is tskit/msprime:0.7.5.

To run a container, you can use docker, Singularity, podman or similar tools supporting docker images.

docker#

docker requires root privilege to run a container:

$ sudo docker run -it tskit/msprime:<release> mspms 10 1 -T

podman#

podman can run an msprime container without root privilege:

$ podman run -it docker.io/tskit/msprime:<release> mspms 10 1 -T

Singularity#

A docker image can also be converted to a Singularity container and then run without root privilege:

$ singularity pull docker://tskit/msprime:<release> msprime-<release>.simg
$ singularity exec msprime-<release>.simg mspms 10 1 -T

Note

It is possible that your current environment may conflict with the environment in the singularity container. There are two workarounds:

Ignore your home with the conflicting environment with --contain or -H </new/path/to/home> -e

$ singularity shell --contain msprime-release-0.7.3.simg
Singularity: Invoking an interactive shell within container...

Singularity msprime-release-0.7.3.simg:~> python3
Python 3.6.8 (default, Jan 14 2019, 11:02:34)
[GCC 8.0.1 20180414 (experimental) [trunk revision 259383]] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import msprime
>>>

or use a different path as your home that does not have a conflicting environment

$ singularity shell -H </new/path/to/home> -e msprime-release-0.7.3.simg
Singularity: Invoking an interactive shell within container...

Singularity msprime-release-0.7.3.simg:~/cnn_classify_demography> python3
Python 3.6.8 (default, Jan 14 2019, 11:02:34)
[GCC 8.0.1 20180414 (experimental) [trunk revision 259383]] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import msprime
>>>

In python get rid of your local path

$ singularity shell msprime-release-0.7.3.simg
Singularity: Invoking an interactive shell within container...

Singularity msprime-release-0.7.3.simg:~> python3
Python 3.6.8 (default, Jan 14 2019, 11:02:34)
[GCC 8.0.1 20180414 (experimental) [trunk revision 259383]] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> for _path in sys.path:
...     if ".local" in _path:
...             sys.path.remove(_path)
...
>>> import msprime
>>>

For more information on Singularity, see https://www.sylabs.io/guides/3.6/user-guide/