Install & Compatibility
Where this runs
tested against v0.47.0 · 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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 14.0s · import 3.627s · 323MB
327MB installed
● package 327MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QiskitRuntimeService
✓ from qiskit_ibm_runtime import QiskitRuntimeService
SamplerV2
✓ from qiskit_ibm_runtime import SamplerV2
EstimatorV2
✓ from qiskit_ibm_runtime import EstimatorV2
Session
✓ from qiskit_ibm_runtime import Session
Sampler
✓ from qiskit_ibm_runtime import SamplerV2 as Sampler
✗ from qiskit_ibm_runtime import Sampler
The original V1 `Sampler` is deprecated/removed. Use `SamplerV2` and alias it if desired for easier migration.
Estimator
✓ from qiskit_ibm_runtime import EstimatorV2 as Estimator
✗ from qiskit_ibm_runtime import Estimator
The original V1 `Estimator` is deprecated/removed. Use `EstimatorV2` and alias it if desired for easier migration.
Options
✓ from qiskit_ibm_runtime.options import Options
✗ from qiskit_ibm_runtime import Options
The `Options` class is not used by V2 primitives and should generally be removed for V2 workflows.
fake_provider
✓ from qiskit_ibm_runtime.fake_provider import FakeSherbrooke
✗ from qiskit.providers.fake_provider import FakeSherbrooke
Fake backends were migrated from `qiskit.providers.fake_provider` to `qiskit_ibm_runtime.fake_provider` in Qiskit 1.0.
This quickstart guides you through authenticating with the IBM Quantum Platform, creating a simple Bell state quantum circuit, and executing it on a real quantum backend using the `SamplerV2` primitive within a session. It emphasizes setting up credentials via environment variables for security and finding a suitable backend.
import os
from qiskit import QuantumCircuit
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler, Session
# Set your IBM Quantum Platform API token and instance CRN as environment variables
# Or save them locally with QiskitRuntimeService.save_account(token="YOUR_API_TOKEN", instance="YOUR_CRN")
# API token: From your IBM Quantum Platform account page (https://quantum.ibm.com/account)
# CRN: From the Instances page on the IBM Quantum Platform (e.g., ibm-q/open/main)
# Initialize the service (ensure API token and instance are set via env vars or saved)
service = QiskitRuntimeService(channel="ibm_quantum_platform")
# Get a least busy backend that supports Sampler
backend = service.least_busy(simulator=False, min_num_qubits=2, max_credits=10)
print(f"Using backend: {backend.name}")
# Create a simple Bell state circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()
# Define the input for Sampler (a PUB: Primitive Unified Bloc)
pubs = [(qc,)] # A single circuit to run
# Run the circuit using SamplerV2 within a session
with Session(service=service, backend=backend) as session:
sampler = Sampler()
job = sampler.run(pubs=pubs)
print(f"Job ID: {job.job_id}")
result = job.result()
# Get the quasi-probability distribution result for the first PUB
quasi_dists = result[0].data.meas.get_counts()
print(f"Quasi-probability distribution: {quasi_dists}")
Debug
Known issues
breakingQiskit Runtime V1 primitives (`Sampler`, `Estimator`, and the `Options` class) are deprecated and have been removed. All code should migrate to use the V2 interfaces (`SamplerV2`, `EstimatorV2`).fixReplace `from qiskit_ibm_runtime import Sampler` with `from qiskit_ibm_runtime import SamplerV2 as Sampler`. Similarly for `Estimator`. Remove usage of the `Options` class, as V2 primitives manage options differently. Refer to the official migration guide.
affects: >=0.21.0 (deprecated), >=0.23.0 (removed support on Aug 15, 2024)
breakingThe `ibm_quantum` channel option for `QiskitRuntimeService` is no longer supported due to the sunset of IBM Quantum Platform Classic. The only valid channels are `ibm_cloud` and `ibm_quantum_platform` (which is the new default).fixWhen initializing `QiskitRuntimeService`, explicitly set `channel="ibm_cloud"` or `channel="ibm_quantum_platform"` if you were previously using `ibm_quantum`. If no channel is specified, `ibm_quantum_platform` is used by default.
affects: >=0.41.0
breakingThe `fake_provider` module, which provides fake backends for testing, has been migrated from `qiskit.providers.fake_provider` to `qiskit_ibm_runtime.fake_provider`.fixUpdate import statements from `from qiskit.providers.fake_provider import ...` to `from qiskit_ibm_runtime.fake_provider import ...`.
affects: Qiskit 1.0.0 and qiskit-ibm-runtime >=0.17.1
deprecatedThe `QiskitRuntimeService.delete_job()` method is deprecated and not supported on the new IBM Quantum Platform.fixAvoid using `QiskitRuntimeService.delete_job()`. Manage jobs via the IBM Quantum Platform dashboard directly.
affects: >=0.24.0
gotchaInitializing a primitive (Sampler/Estimator) outside of a `Session` or `Batch` context manager will result in jobs running in 'job mode'. This means subsequent jobs will not be prioritized, and iterative calls will incur queuing delays.fixAlways execute primitives within a `with Session(...) as session:` block to leverage session benefits like prioritized execution and reduced latency for iterative tasks.
affects: All versions
gotchaAs of March 2024, Qiskit Runtime primitives only accept Instruction Set Architecture (ISA) circuits and observables. Non-ISA inputs must be transpiled before submission.fixEnsure circuits are transpiled to the target backend's ISA using `qiskit.transpile()` before submitting them to the runtime primitives. The Composer on the IBM Quantum Platform can handle this automatically.
affects: >=0.30.0 (and associated service changes)
gotchaConnections to the Qiskit Runtime service can be disrupted, leading to `WebsocketError` when retrieving results, potentially causing loss of computation for long-running jobs.fixThe client library has implemented measures to suppress frequent websocket errors. For critical or long-running jobs, consider implementing robust error handling and retry mechanisms in your application code, especially when reading result objects. Update to `qiskit-ibm-runtime >=0.24.0` for improved resilience.
affects: Affected in <0.24.0, improved in later versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'qiskit_ibm_runtime'
The `qiskit-ibm-runtime` package is not installed in the current Python environment.
fixpip install qiskit-ibm-runtime
Qiskit IBM Runtime service has not been initialized.
The IBM Quantum API token and channel have not been saved for the current user or explicitly provided during `QiskitRuntimeService` instantiation.
fixfrom qiskit_ibm_runtime import QiskitRuntimeService
QiskitRuntimeService.save_account(channel='ibm_quantum', token='YOUR_API_TOKEN')
InvalidCredentialsError: Invalid access token.
The provided IBM Quantum API token is incorrect, expired, or lacks the necessary permissions.
fixObtain a new, valid API token from the IBM Quantum Platform account page and update the saved credentials or the token provided during service initialization.
QiskitRuntimeError: No backend matching requirements.
The specified backend name does not exist, is not currently available, or the user's account does not have access to it.
fixCheck the list of available backends using `service.backends()` and select an active backend that you have access to, or remove the `backend` parameter for automatic selection.
Upgrade
Version history
0.47.0latest on PyPI · released May 12, 2026
Audit
Dependencies
qiskitrequiredCore Qiskit SDK, required for building quantum circuits and operators. qiskit-ibm-runtime v0.41.0 and later are compatible with Qiskit 2.0.
jupyteroptionalRecommended for interactive development in notebooks.
matplotliboptionalCommonly used for visualizing results, especially histograms.