Getting started#


Qiskit Aer depends on the main Qiskit package which has its own Qiskit Installation guide detailing the installation options for Qiskit and its supported environments/platforms. You should refer to that first. Then the information here can be followed which focuses on the additional installation specific to Qiskit Aer.

The simplest way to get started is to follow the installation guide for Qiskit here

In your virtual environment where you installed Qiskit, add qiskit-aer, e.g.:

pip install qiskit-aer

Installing GPU support

In order to install and run the GPU supported simulators on Linux, you need CUDA® 10.1 or newer previously installed. CUDA® itself would require a set of specific GPU drivers. Please follow CUDA® installation procedure in the NVIDIA® web.

If you want to install our GPU supported simulators, you have to install this other package:

pip install qiskit-aer-gpu

This will overwrite your current qiskit-aer package installation giving you the same functionality found in the canonical qiskit-aer package, plus the ability to run the GPU supported simulators: statevector, density matrix, and unitary.

Note: This package is only available on x86_64 Linux. For other platforms that have CUDA support you will have to build from source.

Installing Qiskit Aer from source allows you to access the most recently updated version under development instead of using the version in the Python Package Index (PyPI) repository. This will give you the ability to inspect and extend the latest version of the Qiskit Aer code more efficiently.

Since Qiskit Aer depends on Qiskit, and its latest changes may require new or changed features of Qiskit, you should first follow Qiskit’s “Install from source” instructions here

Installing Qiskit Aer from Source

Clone the Qiskit Aer repo via git.

git clone

The common dependencies can then be installed via pip, using the requirements-dev.txt file, e.g.:

cd qiskit-aer
pip install -r requirements-dev.txt

As any other Python package, we can install from source code by just running:

qiskit-aer$ pip install .

This will build and install Aer with the default options which is probably suitable for most of the users. There’s another Pythonic approach to build and install software: build the wheels distributable file.

qiskit-aer$ pip install build
qiskit-aer$ python -I -m build --wheel

See here for detailed installation information.

Building with GPU support

Qiskit Aer can exploit GPU’s horsepower to accelerate some simulations, specially the larger ones. GPU access is supported via CUDA® (NVIDIA® chipset), so to build with GPU support, you need to have CUDA® >= 10.1 preinstalled. See install instructions here Please note that we only support GPU acceleration on Linux platforms at the moment.

Once CUDA® is properly installed, you only need to set a flag so the build system knows what to do:


For example,

qiskit-aer$ python ./ bdist_wheel -- -DAER_THRUST_BACKEND=CUDA

See here for detailed GPU support information.

Building with MPI support

Qiskit Aer can parallelize its simulation on the cluster systems by using MPI. This can extend available memory space to simulate quantum circuits with larger number of qubits and also can accelerate the simulation by parallel computing. To use MPI support, any MPI library (i.e. OpenMPI) should be installed and configured on the system.

Qiskit Aer supports MPI both with and without GPU support. Currently following simulation methods are supported to be parallelized by MPI.

  • statevector

  • density_matrix

  • unitary

To enable MPI support, the following flag is needed for build system based on CMake.


For example,

qiskit-aer$ python ./ bdist_wheel -- -DAER_MPI=True

See here for detailed MPI support information.

Simulating your first quantum program with Qiskit Aer#

Now that you have Qiskit Aer installed, you can start simulating a quantum circuit. Here is a basic example:

import qiskit
from qiskit_aer import AerSimulator

# Generate 3-qubit GHZ state
circ = qiskit.QuantumCircuit(3)
circ.h(0), 1), 2)

# Construct an ideal simulator
aersim = AerSimulator()

# Perform an ideal simulation
result_ideal = qiskit.execute(circ, aersim).result()
counts_ideal = result_ideal.get_counts(0)
print('Counts(ideal):', counts_ideal)
# Counts(ideal): {'000': 493, '111': 531}

Ready to get going?…#

Dive into the tutorials

Find out about Qiskit Aer

Qiskit Aer tutorials