Migrate to using Qiskit Runtime primitives

This guide describes key patterns of behavior and use cases with code examples to help you migrate code from the legacy qiskit-ibmq-provider package to use the Qiskit Runtime primitives.

Primitives are the recommended tool to write quantum algorithms, as they encapsulate common device queries seen in application packages and allow for managed performance through the Qiskit Runtime service. However, if your algorithm requires more granular information, such as pre-shot measurements, the primitives might not provide the desired abstraction level.

The Qiskit Runtime primitives implement the reference Sampler and Estimator interfaces found in qiskit.primitives. These interfaces let you switch between primitive implementations with minimal code changes. Different primitive implementations can be found in the qiskit, qiskit_aer, and qiskit_ibm_runtime libraries. Each implementation serves a specific purpose:

  • The primitives in qiskit can perform local state vector simulations - useful for quickly prototyping algorithms.

  • The primitives in qiskit_aer give access to the local Aer simulators for tasks such as noisy simulation.

  • The primitives in qiskit_ibm_runtime provide access to cloud simulators and real hardware through the Qiskit Runtime service. They include exclusive features such as built-in circuit optimization and error mitigation support.


The only primitives that provide access to the Qiskit Runtime service are those imported from qiskit_ibm_runtime (Qiskit Runtime Primitives).

When migrating, the key to writing an equivalent algorithm using primitives is to first identify what is the minimal unit of information your algorithm is based on:

  • If it uses an expectation value, you will need an Estimator.

  • If it uses a probability distribution (from sampling the device), you will need a Sampler.

After determining which primitive to use, identify where the algorithm accesses the backend. Look for the call to backend.run(). Next, you will replace this call with the respective primitive call, as shown in the following examples.

Algorithm developers who need to refactor algorithms to use primitives instead of backend.run should refer to these topics:

The following topics are use cases with code migration examples:

Why use Qiskit Runtime?



Runtime Primitives

Simplified algorithm building blocks

Flexible interface

Elastic compute integration

Queuing efficiency

Data caching

Error mitigation support

SAAS enablement


  • Not supported

  • Full support

  • Future support

Benefits of using Qiskit Runtime:

  • Simplify algorithm design and optimization.

  • Run circuits faster by using sessions - a context manager designed to efficiently manage iterative workloads and minimize artificial latency between quantum and classical sub-components.

  • Access our most powerful quantum systems with our latest performance and hardware optimization, including capabilities like error suppression and mitigation.

  • Easily integrate Qiskit Runtime with your cloud or on-premise classical compute resources by using the quantum serverless toolkit.

Simplified interface:

Use primitives to write code more efficiently. For details, see the examples topics, such as Using Estimator to design an algorithm.

Two code snippets, side by side

Fig. 4 Code without primitives, and the same code after being rewritten to use primitives.


Users might have the following questions when planning to migrate their code to Qiskit Runtime:

Which channel should I use?

After deciding to use Qiskit Runtime primitives, the user must determine whether to access Qiskit Runtime through IBM Cloud or IBM Quantum Platform. Some information that might help you decide includes:

  • The available plans:

    • Qiskit Runtime is available in both the Open (free access) or Premium (contract-based paid access) plan on IBM Quantum Platform. See IBM Quantum access plans for details.

    • Qiskit Runtime is accessible through the Lite (free access) or Standard (pay-as-you-go access) plan in IBM Cloud. See Plans for details.

  • The use case requirements:

    • IBM Quantum Platform offers a visual circuit composer (Quantum Composer) and a Jupyter Notebook environment (Quantum Lab).

    • IBM Cloud offers a cloud native service that is ideal if users need to integrate quantum capabilities with other cloud services.

How do I set up my channel?

After deciding which channel to use to interact with Qiskit Runtime, you can get set up on either platform using the instructions below:

Should I modify the Qiskit Terra algorithms?

As of v0.22, Qiskit Terra algorithms use Qiskit Runtime primitives. Thus, there is no need for users to modify amplitude estimators or any other Qiskit Terra algorithms.

Which primitive should I use?

When choosing which primitive to use, you first need to understand whether the algorithm uses a quasi-probability distribution sampled from a quantum state (a list of quasi-probabilities), or an expectation value of a certain observable with respect to a quantum state (a real number).

A probability distribution is often of interest in optimization problems that return a classical bit string, encoding a certain solution to a problem at hand. In these cases, you might be interested in finding a bit string that corresponds to a ket value with the largest probability of being measured from a quantum state, for example.

An expectation value of an observable could be the target quantity in scenarios where knowing a quantum state is not relevant. This often occurs in optimization problems or chemistry applications. For example, when trying to discover the extremal energy of a system.