Installation

Installation#

There are two main options for installing msprime:

  1. Via Conda: the recommended options for most users

  2. Via Pip: more flexibility and control for advanced users

Via Conda#

Convenient conda packages are available for Python 3.10 and greater on Linux, macOS and Windows. These pre-built binary packages are built using conda-forge.

Quick Start#

  1. Install conda using miniconda. Make sure you follow the instructions to fully activate your conda installation!

  2. Set up the conda-forge channel using conda config --add channels conda-forge.

  3. Create a conda environment and install msprime into it: conda create -n msprime-env msprime

  4. Activate the environment: conda activate msprime-env

  5. 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 a macOS 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.10 or greater and pip. Run

$ python3 -m pip --version

to make sure you see Python 3.10 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
Contents