Install Qiskit

(opens in a new tab)

Whether you will work locally or in a cloud environment, the first step for all users is to install Qiskit. For those wanting to run on a real quantum processing unit (QPU), your next step is to choose one of two channels in order to access IBM® QPUs: IBM Quantum Platform or IBM Cloud®.

Install the Qiskit SDK and the Qiskit Runtime client

1. Install Python. Check the "Programming Language" section on the Qiskit PyPI project page to determine which Python versions are supported by the most recent release. For download instructions, see the Python Beginners Guide.

   It is recommended that you use Python virtual environments to separate Qiskit from other applications.

   Note

   These instructions use the standard Python distribution from pypi.org. However, you can use other Python distributions, such as Anaconda or miniconda, along with other dependency management workflows like Poetry.

   If you're new to virtual environments, click here for more information.

   A virtual Python environment is an isolated space to work with Python for a specific purpose — so you can install whatever packages you wish, and set up libraries, dependencies, and so on, without affecting the "base" Python environment on your machine.

   One important advantage of a virtual environment is that if your Python environment becomes corrupted somewhere along the way, you can easily delete the virtual environment and start over!

   Choose a preferred location in which to store information about your virtual environments. Commonly they're stored in a directory named .venv within a user's home directory.

   First, create a minimal environment with only Python installed in it.

   macOS

   Linux

   Windows

   python3 -m venv /path/to/virtual/environment

   Next, activate your new environment.

   macOS

   Linux

   Windows

   source /path/to/virtual/environment/bin/activate

2. Install pip if it's not already installed in your environment. Pip is a Python package manager that you use to install Qiskit and other Python packages. Use pip list to see what is in your virtual environment. In most Python environments, pip is already installed.

3. Install the Qiskit SDK. If you plan to run jobs on quantum hardware, also install Qiskit Runtime.

   pip install qiskit

   pip install qiskit-ibm-runtime

   If you intend to use visualization functionality or Jupyter notebooks, it is recommended to install Qiskit with the extra visualization support ('qiskit[visualization]').

   Default

   zsh

   pip install qiskit[visualization]

4. If you want to run a Jupyter notebook with the Qiskit packages you just installed, you will need to install Jupyter in your environment.

   pip install jupyter

   Then open your notebook as follows:

   jupyter notebook path/to/notebook.ipynb

If you are planning to work locally and use simulators built into Qiskit, then your installation is done. If you want to run jobs on IBM QPUs, next select an access channel and finish your setup.

Troubleshooting

Failed building wheel for SOME_PACKAGE
...
build/temp.linux-x86_64-3.5/_openssl.c:498:30: fatal error
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1

Operating system support

Qiskit strives to support as many operating systems as possible, but due to limitations in available testing resources and operating system availability, not all operating systems can be supported. Operating system support for Qiskit is broken into three tiers with different levels of support for each tier. For platforms outside these, such as FreeBSD or WebAssembly (WASI), Qiskit may still be installable, but it is not tested and you will have to build Qiskit (and likely Qiskit’s dependencies) from source.

Additionally, Qiskit only supports the CPython implementation of the Python language. Running with other Python interpreters such as PyPy is not supported.

Next steps