Unofficial installation guide of qiskit - t-imamichi/qiskit-utility GitHub Wiki

This is an unofficial installation guide of qiskit as of April 23, 2021.

Index

Introduction

Although there is an official documentation, I describe the details for those who use the official build of Python rather than Anaconda Python for each platform (Windows, macOS, Ubuntu). I recommend Anaconda users to follow the the official documentation. Note that I do not recommend pyenv because I saw some troubles with Qiskit.

I suppose the following platforms in this guide.

  • Windows 10 1809 or newer
  • macOS High Sierra or newer
  • Ubuntu 18.04 or newer

Prerequisites

If you use Google Colaboratory, you need just a browser. See Qiskit on Google Colab. The following instructions are for those who install qiskit locally.

Windows

macOS

  • Xcode command line tools
$ xcode-select --install

Ubuntu

  • Python3 and libraries
$ sudo apt install python3 libpython3-dev python3-venv build-essential

Python virtual environment management

I strongly recommend to use a virtual environment management for Python such as venv. You can switch between environments with different qiskit versions. I use venv in this guide. If you use Anaconda, please take a look at an article "Using pip in a conda environment".

You can create a new environment "my_env" as follows. You need to do it only once.

(macOS and Ubuntu)
$ python3 -m venv /path/to/my_env  # make an environment

(Windows)
$ python -m venv \path\to\my_env  # make an environment

You can activate your environment as follows.

(macOS and Ubuntu)
$ source /path/to/my_env/bin/activate  # activate an environment

(Windows)
$ \path\to\my_env\Scripts\activate  # activate an environment

I show sample scripts for macOS and Ubuntu in the following sections. Note that Windows users need to change them accordingly.

Install Qiskit

You need pip 19 or newer to install the binary package of Aer. If you have a build issue of Aer, please check the pip version. See the the official documentation for more information.

Full installation

$ python3 -m venv /path/to/envs/qiskit
$ source /path/to/envs/qiskit/bin/activate
(qiskit)$ python -m pip install -U pip wheel setuptools
(qiskit)$ pip install 'qiskit[all]'

Lightweight installation (without qiskit aqua)

If you want only the basic functionality of qiskit, you can install the core packages only.

$ python3 -m venv /path/to/envs/qiskit
$ source /path/to/envs/qiskit/bin/activate
(qiskit)$ python -m pip install -U pip wheel setuptools
(qiskit)$ pip install 'qiskit-terra[visualization]' qiskit-ibmq-provider qiskit-aer notebook

Qiskit on Google Colab

You can install Qiskit on Google Colaboratory as follows.

%pip install qiskit

Development version of Qiskit

If you want to contribute to Qiskit, you need to install the development version of Qiskit by cloning the Github repository. The following is an example to install the development version of Qiskit Terra and Aqua in a new environment 'qiskit-dev'.

$ git clone [email protected]:(your account)/qiskit-terra.git  # your cloned repository of Terra
$ python3 -m venv /path/to/envs/qiskit-dev
$ source /path/to/envs/qiskit-dev/bin/activate
(qiskit-dev)$ python -m pip install -U pip wheel setuptools
(qiskit-dev)$ cd qiskit-terra
(qiskit-dev)$ git checkout (your Terra branch)
(qiskit-dev)$ pip install -e '.[visualization]'
(qiskit-dev)$ pip install qiskit-aer

If you want to build Aer by yourself, see the contributing guide for Aer.

Additional step for Windows

Qiskit-aqua depends on CVXOPT and its binary for Windows requires a special build of Numpy. You need to download and install a relevant numpy wheel in the following link.

For example, if you use Python 3.6 on Windows, you download "numpy-1.16.4+mkl-cp36-cp36m-win_amd64.whl" and install it as follows.

# before you install qiskit
(qiskit)$ pip install numpy-1.16.4+mkl-cp36-cp36m-win_amd64.whl

Upgrade Qiskit

You can upgrade qiskit as follows. Note that I recommend the following steps only for minor version-ups.

$ source /path/to/envs/qiskit/bin/activate
(qiskit)$ python -m pip install -U pip wheel setuptools
(qiskit)$ pip install -U qiskit

If a major version-up is released, I recommend to create a new virtual environment to test the new functionality. It is because the new version may break the compatibility to the previous versions.

Configure your credentials

Since July 2019, you need to update your credential once. See the official guide.

  • Register your token (replace 'MY_API_TOKEN' and 'MY_QCONSOLE_URL' with your token and URL). You run the following script just once. Qiskit generates qiskitrc file including your credentials.
$ source /path/to/envs/qiskit/bin/activate
(qiskit) $ python
>>> from qiskit import IBMQ
>>> IBMQ.save_account('MY_API_TOKEN')
>>> exit()
  • Load your account when you run your script. You can call IBM Q APIs if you run IBMQ.load_account().
    • If you get an error when calling IBMQ.load_account(), check whether your credentials in ~/.qiskit/qiskitrc file are correct. If not, remove qiskitrc and try IBMQ.save_account() with correct ones again.
(qiskit) $ python
>>> from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister, execute
>>> qr = QuantumRegister(2)
>>> cr = ClassicalRegister(2)
>>> qc = QuantumCircuit(qr, cr)
>>> qc.h(qr[0])
>>> qc.cx(qr[0], qr[1])
>>> qc.measure(qr, cr)
>>> print(qc)
         ┌───┐        ┌─┐
q0_0: |0>┤ H ├──■─────┤M├
         └───┘┌─┴─┐┌─┐└╥┘
q0_1: |0>─────┤ X ├┤M├─╫─
              └───┘└╥┘ ║ 
 c0_0: 0 ═══════════╬══╩═
                    ║    
 c0_1: 0 ═══════════╩════

>>> # execute the circuit on a simulator
>>> from qiskit import Aer
>>> Aer.backends()
[<QasmSimulator('qasm_simulator') from AerProvider()>,
 <StatevectorSimulator('statevector_simulator') from AerProvider()>,
 <UnitarySimulator('unitary_simulator') from AerProvider()>]
>>> result = execute(qc, backend=Aer.get_backend('qasm_simulator')).result()
>>> print(result.get_counts())
{'00': 520, '11': 504}
                         
>>> # execute the circuit on a real device
>>> from qiskit import IBMQ
>>> provider = IBMQ.load_account()
>>> print(provider.backends())
[<IBMQSimulator('ibmq_qasm_simulator') from IBMQ(hub='ibm-q', group='open', project='main')>,
 <IBMQBackend('ibmqx2') from IBMQ(hub='ibm-q', group='open', project='main')>,
 <IBMQBackend('ibmq_16_melbourne') from IBMQ(hub='ibm-q', group='open', project='main')>,
 <IBMQBackend('ibmq_vigo') from IBMQ(hub='ibm-q', group='open', project='main')>,
 <IBMQBackend('ibmq_ourense') from IBMQ(hub='ibm-q', group='open', project='main')>,
 <IBMQBackend('ibmq_london') from IBMQ(hub='ibm-q', group='open', project='main')>,
 <IBMQBackend('ibmq_burlington') from IBMQ(hub='ibm-q', group='open', project='main')>,
 <IBMQBackend('ibmq_essex') from IBMQ(hub='ibm-q', group='open', project='main')>]
>>> result = execute(qc, backend=provider.get_backend('ibmq_vigo')).result()
Error checking job status using websocket, retrying using HTTP.
... It may take a long time ...
>>> print(result.get_counts())
{'01': 10, '00': 579, '10': 10, '11': 425}

Try tutorials

  • Clone the repository
$ git clone https://github.com/Qiskit/qiskit-iqx-tutorials.git
  • Start Jupyter notebook
$ cd qiskit-iqx-tutorials
$ source /path/envs/qiskit/bin/activate
(qiskit) $ jupyter notebook

Configure Pycharm

If you develop your programs on Pycharm, you need to register your environment to Pycharm.

  • File > Settings > Project > Project Interpreter > "Gear" mark > Add > Virtualenv Environment > Existing environment > Interpreter
  • Choose "python" in your environment
    • usually located in /path/to/envs/qiskit/bin/python (macOS and Linux), \path\to\envs\qiskit\Scripts\python.exe (Windows)

FAQ