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
- Visual C++ runtime component (one of the following items)
- Python
- Official build
- If you want to use CPLEX with Aqua, you need to install Python 3.6 or 3.7 or 3.8.
- (Optional, if you need to build any binary) Build Tools for Visual Studio 2017
macOS
- Xcode command line tools
$ xcode-select --install
- Python
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, removeqiskitrc
and tryIBMQ.save_account()
with correct ones again.
- If you get an error when calling
(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}
- See the official documentation for the details.
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)