Installation¶

Quick Start¶

From QuTiP version 4.6 onwards, you should be able to get a working version of QuTiP with the standard

pip install qutip

It is not recommended to install any packages directly into the system Python environment; consider using pip or conda virtual environments to keep your operating system space clean, and to have more control over Python and other package versions.

You do not need to worry about the details on the rest of this page unless this command did not work, but do also read the next section for the list of optional dependencies. The rest of this page covers installation directly from conda, installation from source, and additional considerations when working on Windows.

General Requirements¶

QuTiP depends on several open-source libraries for scientific computing in the Python programming language. The following packages are currently required:

Package	Version	Details
Python	3.6+
NumPy	1.16+
SciPy	1.0+	Lower versions may have missing features.

In addition, there are several optional packages that provide additional functionality:

Package	Version	Details
`matplotlib`	1.2.1+	Needed for all visualisation tasks.
`cython`	0.29.20+	Needed for compiling some time-dependent Hamiltonians.
`cvxpy`	1.0+	Needed to calculate diamond norms.
C++ Compiler	GCC 4.7+, MS VS 2015	Needed for compiling Cython files, made when using string-format time-dependence.
`pytest`, `pytest-rerunfailures`	5.3+	For running the test suite.
LaTeX	TeXLive 2009+	Needed if using LaTeX in matplotlib figures, or for nice circuit drawings in IPython.

In addition, there are several additional packages that are not dependencies, but may give you a better programming experience. IPython provides an improved text-based Python interpreter that is far more full-featured that the default interpreter, and runs in a terminal. If you prefer a more graphical set-up, Jupyter provides a notebook-style interface to mix code and mathematical notes together. Alternatively, Spyder is a free integrated development environment for Python, with several nice features for debugging code. QuTiP will detect if it is being used within one of these richer environments, and various outputs will have enhanced formatting.

Installing with conda¶

QuTiP is designed to work best when using the Anaconda or Intel Python distributions that support the conda package management system. It is still possible to use pip to install QuTiP while using conda, but uniformly using conda will make complete dependency management easier.

If you already have your conda environment set up, and have the conda-forge channel available, then you can install QuTiP using:

conda install qutip

This will install the minimum set of dependences, but none of the optional packages.

Adding the conda-forge channel¶

To install QuTiP from conda, you will need to add the conda-forge channel. The following command adds this channel with lowest priority, so conda will still try and install all other packages normally:

conda config --append channels conda-forge

If you want to change the order of your channels later, you can edit your .condarc (user home folder) file manually, but it is recommended to keep defaults as the highest priority.

New conda environments¶

The default Anaconda environment has all the Python packages needed for running QuTiP installed already, so you will only need to add the conda-forge channel and then install the package. If you have only installed Miniconda, or you want a completely clean virtual environment to install QuTiP in, the conda package manager provides a convenient way to do this.

To create a conda environment for QuTiP called qutip-env:

conda create -n qutip-env python qutip

This will automatically install all the necessary packages, and none of the optional packages. You activate the new environment by running

conda activate qutip-env

You can also install any more optional packages you want with conda install, for example matplotlib, ipython or jupyter.

Installing from Source¶

Official releases of QuTiP are available from the download section on the project’s web pages, and the latest source code is available in our GitHub repository. In general we recommend users to use the latest stable release of QuTiP, but if you are interested in helping us out with development or wish to submit bug fixes, then use the latest development version from the GitHub repository.

You can install from source by using the Python-recommended PEP 517 procedure, or if you want more control or to have a development version, you can use the low-level build procedure with setuptools.

PEP 517 Source Builds¶

The easiest way to build QuTiP from source is to use a PEP-517-compatible builder such as the build package available on pip. These will automatically install all build dependencies for you, and the pip installation step afterwards will install the minimum runtime dependencies. You can do this by doing (for example)

pip install build
python -m build <path to qutip>
pip install <path to qutip>/dist/qutip-<version>.whl

The first command installs the reference PEP-517 build tool, the second effects the build and the third uses pip to install the built package. You will need to replace <path to qutip> with the actual path to the QuTiP source code. The string <version> will depend on the version of QuTiP, the version of Python and your operating system. It will look something like 4.6.0-cp39-cp39-manylinux1_x86_64, but there should only be one .whl file in the dist/ directory, which will be the correct one.

Direct Setuptools Source Builds¶

This is the method to have the greatest amount of control over the installation, but it the most error-prone and not recommended unless you know what you are doing. You first need to have all the runtime dependencies installed. The most up-to-date requirements will be listed in pyproject.toml file, in the build-system.requires key. As of the 4.6.0 release, the build requirements can be installed with

pip install setuptools wheel 'cython>=0.29.20' 'numpy>=1.16.6,<1.20' 'scipy>=1.0'

or similar with conda if you prefer. You will also need to have a functional C++ compiler installed on your system. This is likely already done for you if you are on Linux or macOS, but see the section on Windows installations if that is your operating system.

To install QuTiP from the source code run:

python setup.py install

To install OpenMP support, if available, run:

python setup.py install --with-openmp

This will attempt to load up OpenMP libraries during the compilation process, which depends on you having suitable C++ compiler and library support. If you are on Linux this is probably already done, but the compiler macOS ships with does not have OpenMP support. You will likely need to refer to external operating-system-specific guides for more detail here, as it may be very non-trivial to correctly configure.

If you wish to contribute to the QuTiP project, then you will want to create your own fork of the QuTiP git repository, clone this to a local folder, and install it into your Python environment using:

python setup.py develop

When you do import qutip in this environment, you will then load the code from your local fork, enabling you to edit the Python files and have the changes immediately available when you restart your Python interpreter, without needing to rebuild the package. Note that if you change any Cython files, you will need to rerun the build command.

You should not need to use sudo (or other superuser privileges) to install into a personal virtual environment; if it feels like you need it, there is a good chance that you are installing into the system Python environment instead.

Installation on Windows¶

As with other operating systems, the easiest method is to use pip install qutip, or use the conda procedure described above. If you want to build from source or use runtime compilation with Cython, you will need to have a working C++ compiler.

You can download the Visual Studio IDE from Microsoft, which has a free Community edition containing a sufficient C++ compiler. This is the recommended compiler toolchain on Windows. When installing, be sure to select the following components:

Windows “X” SDK (where “X” stands for your version: 7/8/8.1/10)
Visual Studio C++ build tools

You can then follow the installation from source section as normal.

Important

In order to prevent issues with the PATH environment variable not containing the compiler and associated libraries, it is recommended to use the developer command prompt in the Visual Studio installation folder instead of the built-in command prompt.

The Community edition of Visual Studio takes around 10GB of disk space. If this is prohibitive for you, it is also possible to install only the build tools and necessary SDKs instead, which should save about 2GB of space.

Verifying the Installation¶

QuTiP includes a collection of built-in test scripts to verify that an installation was successful. To run the suite of tests scripts you must also have the pytest testing library. After installing QuTiP, leave the installation directory, run Python (or IPython), and call:

import qutip.testing
qutip.testing.run()

This will take between 10 and 30 minutes, depending on your computer. At the end, the testing report should report a success; it is normal for some tests to be skipped, and for some to be marked “xfail” in yellow. Skips may be tests that do not run on your operating system, or tests of optional components that you have not installed the dependencies for. If any failures or errors occur, please check that you have installed all of the required modules. See the next section on how to check the installed versions of the QuTiP dependencies. If these tests still fail, then head on over to the QuTiP Discussion Board or the GitHub issues page and post a message detailing your particular issue.

Checking Version Information¶

QuTiP includes an “about” function for viewing information about QuTiP and the important dependencies installed on your system. To view this information:

import qutip
qutip.about()