qiskit-aer

library0.17.2pypypi✓ verified 23d ago

Qiskit Aer is a high-performance simulator backend for Qiskit, designed for fast and accurate simulation of quantum circuits on classical computers. It supports various simulation methods, including statevector, density matrix, extended stabilizer, and matrix product state, along with advanced noise modeling capabilities. The current version is 0.17.2, and it typically releases new versions in sync with major Qiskit releases to maintain compatibility.

ai-ml data workflow

pip install qiskit-aer

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QISKIT-AER

qiskit-aer

ai-mlpythonv0.17.2

Install

9.8s avg

Import

1428ms

Disk

316MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.17.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 9.8s · import 1.428s · 313MB

316MB installed

● package 316MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AerSimulator

✓ from qiskit_aer import AerSimulator

Aer

✓ from qiskit_aer import Aer

✗ from qiskit.providers.aer import Aer

The `Aer` object is still used for getting specific simulator backends, but `AerSimulator` is the recommended direct import for the default simulator in newer Qiskit versions. The path `qiskit.providers.aer` is for legacy Qiskit versions.

This example demonstrates how to create a simple Bell state circuit, select the default AerSimulator backend, and execute the circuit to obtain measurement counts.

from qiskit import QuantumCircuit, transpile from qiskit_aer import AerSimulator # Construct quantum circuit circ = QuantumCircuit(2, 2) circ.h(0) circ.cx(0, 1) circ.measure([0,1], [0,1]) # Select the AerSimulator simulator = AerSimulator() # Run and get counts compiled_circuit = transpile(circ, simulator) job = simulator.run(compiled_circuit, shots=1000) result = job.result() counts = result.get_counts(circ) print("Shot counts:", counts)

Debug

Known issues

breakingQiskit Aer versions prior to 0.17.0 are not fully compatible with Qiskit 2.0 and later. Significant API changes in Qiskit 2.0 require corresponding updates in Qiskit Aer.

fix

Upgrade `qiskit-aer` to 0.17.0 or newer (e.g., `pip install qiskit-aer>=0.17.0`). Ensure your `qiskit` package is also up-to-date (e.g., `pip install qiskit>=2.0`).

affects: <0.17.0 (when used with qiskit>=2.0)

deprecatedDirectly accessing simulator backends via `Aer.get_backend('aer_simulator')` is less explicit than importing the `AerSimulator` class directly. While still functional, the direct class import is the recommended pattern.

fix

Prefer `from qiskit_aer import AerSimulator; simulator = AerSimulator()` over `from qiskit_aer import Aer; simulator = Aer.get_backend('aer_simulator')`.

affects: All versions (more relevant with qiskit>=1.0)

gotchaQiskit Aer has specific Python version requirements that can change between releases. For example, version 0.16.1 dropped support for Python 3.8 and added support for Python 3.13.

fix

Always check the `Requires-Python` metadata on PyPI or the official documentation for `qiskit-aer` and `qiskit` to ensure your Python environment is compatible.

affects: 0.16.1 onwards

gotchaEnabling GPU acceleration for `qiskit-aer` requires specific system configurations, including CUDA Toolkit and drivers. Setup can be complex and may require custom builds or specific installation flags.

fix

Consult the official Qiskit Aer documentation for detailed GPU installation instructions specific to your operating system and hardware. Ensure all necessary NVIDIA CUDA components are correctly installed and configured.

affects: All versions attempting GPU acceleration

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'qiskit_aer'

The qiskit-aer package is not installed in your current Python environment.

fix

pip install qiskit-aer

ImportError: cannot import name 'Aer' from 'qiskit_aer'

The 'Aer' object, which was previously used to obtain simulator backends, has been deprecated and removed in recent versions of Qiskit Aer in favor of direct import of 'AerSimulator'.

fix

from qiskit_aer import AerSimulator
simulator = AerSimulator()

ERROR: Failed building wheel for qiskit-aer

The installation of qiskit-aer requires compilation of C++ components, and your system is missing the necessary C++ compilers or Python development headers.

fix

Ensure you have C++ build tools (e.g., Visual Studio Build Tools on Windows, `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS) and Python development headers installed before running `pip install qiskit-aer`.

QiskitError: 'The AerSimulator backend doesn't support the specified basis_gates'

The quantum circuit contains gates that are not natively supported by the AerSimulator with its default configuration or the specific simulation method chosen.

fix

Transpile your circuit to a basis set compatible with the simulator's default gates (e.g., `['sx', 'rz', 'cx', 'id']` or `['u1', 'u2', 'u3', 'cx', 'id']` for standard simulations) using `qiskit.transpile` before execution.

Upgrade

Version history

0.17.2latest on PyPI · released Sep 17, 2025

Audit

Dependencies

qiskitrequiredQiskit Aer is a backend for Qiskit; recent versions (0.17.x+) require Qiskit 2.0+ for full compatibility and API alignment.

python-dateutilrequiredAdded as a requirement in qiskit-aer 0.17.1.

Agent activity

55 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Qiskit/qiskit-aer ↗

packagehttps://pypi.org/project/qiskit-aer/ ↗

homepagehttps://qiskit.org ↗