Quick start

To install the package qutip-qip from PyPI, use

pip install qutip-qip

Migrating from qutip.qip

As the Introduction suggested, this package is based on a module in the QuTiP package qutip.qip. If you were using the qutip package and now want to try out the new features included in this package, you can simply install this package and replace all the qutip.qip in your import statement with qutip_qip. Everything should work smoothly as usual.


This package is built upon QuTiP, of which the installation guide can be found at on QuTiP Installation. The only difference is that C++ compilers are not required here since there is no run-time compiling for qutip-qip. The minimal Python version supported is Python 3.7.

In particular, following packages are necessary for running qutip-qip

numpy scipy cython qutip

The following to packages are used for plotting and testing:

matplotlib pytest

In addition

sphinx numpydoc sphinx_rtd_theme

are used to build and test the documentation.

Additional software for Plotting Circuits

In order to plot circuits, the following non-Python packages are needed:


The circuit plotting function in QuTiP uses LaTeX and a few LaTeX packages including qcircuit, pdfcrop and braket.

For Linux and Mac : You need to install a TeX distribution such as TeX Live. You can either install it through apt-get/brew or using their installer on the website. If you would prefer to avoid installing the full texlive distribution (which is a few Gigabyte large), this link has some useful discussion on selectively installing part of the packages. In particular:

  • braket will be installed as a part of texlive-latex-extra

  • qcircuit will be installed as a part of texlive-pictures

  • pdfcrop and pdflatex are installed when a minimal texlive is installed.


Do not install pdfcrop via pip because the package’s old dependencies will clash with newer dependencies of other programs installed in the qutip-qip virtual environment.

For Windows : We recommend installing MiKTeX, which will automatically install necessary packages like qcircuit for you when it is used. It will only take a few more minutes in your first attempt at plotting a circuit. In addition, you also need to install perl for pdfcrop.

ImageMagick and Ghostscript

In order to display the circuit in Jupyter notebook, we need to convert it to png format. To do that, you will need to install Ghostscript and ImageMagick. The first is responsible for reading the pdf file while the second will convert it to png.


You might need to make changes to policy.xml if the following error occurs :

RuntimeError: convert-im6.q16: not authorized `qcirc.pdf' @ error/constitute.c/ReadImage/412.
convert-im6.q16: no images defined `qcirc.png' @ error/convert.c/ConvertImageCommand/3258.

The output of a circuit plot will be output in a Jupyter notebook. In your virtual environment, start a Jupyter notebook server and run your examples in a notebook. If you try to access a circuit plot in a terminal or IPython console, you will only be able to access the location of this image in your device’s memory.


To convert the circuit into svg format, you will need to install pdf2svg. Please visit their website for installation guide.


If you want to check whether all dependencies are installed, see if the following three commands work correctly: pdflatex, pdfcrop and magick anypdf.pdf anypdf.png, where anypdf.pdf is any pdf file you have.

Install qutip-qip from source code

To install the package, download to source code from GitHub website and run

pip install .

under the directory containing the setup.cfg file.

If you want to edit the code, use instead

pip install -e .

To test the installation from a download of the source code, run from the qutip-qip directory

pytest tests