Registry / ai-ml / qiskit-ibm-runtime

qiskit-ibm-runtime

JSON →
library0.47.0pypypi✓ verified 87d ago

Qiskit IBM Runtime is the official client library for interacting with the IBM Quantum Platform's Qiskit Runtime service. It streamlines quantum computations by providing optimized implementations of Qiskit primitives (Sampler and Estimator) for IBM Quantum hardware, leveraging classical computing resources for tasks like error suppression and mitigation. The library is currently at version 0.46.1 and requires Python >=3.10.

pip install qiskit-ibm-runtime
INSTALL
IMPORT
SIG · QISKIT-IBM-RUNTIME
Q
qiskit-ibm-runtime
ai-mlpythonv0.47.0
Install
14.0s avg
Import
3627ms
Disk
327MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
build_error
glibc
py 3.103.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`).
fix
Replace `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).
fix
When 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`.
fix
Update 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.
fix
Avoid 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.
fix
Always 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.
fix
Ensure 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.
fix
The 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.
fix
pip 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.
fix
from 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.
fix
Obtain 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.
fix
Check 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.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources
qiskit-ibm-runtime — pip install qiskit-ibm-runtime · libregistry