Getting started

This tutorial walks you through the steps to set up a Qiskit Runtime service instance, log in to your service instance, and run your first job on a quantum computer.

If you are an entity upgrading from an IBM Quantum program who needs to set up Qiskit Runtime, refer to Upgrade from the Open plan for instructions to set up a cloud account, a service instance, and work with users.
If your organization has a more complex structure, refer to Plan Qiskit Runtime for an organization for more flexible instructions to set up a service instance and work with users.
If you are an individual setting up the Qiskit Runtime service for the first time or if you have been invited to an instance by an administrator, continue following the steps in this topic.

Create a service instance

If you already created a Qiskit Runtime service instance or were invited to one by an administrator, skip to the next step. To determine whether you already have access to an instance, check your IBM Cloud Instances page. If you have one or more instances shown, you can skip ahead to Install Qiskit packages.

From the Qiskit Runtime Provisioning page, choose the appropriate service plan, depending on what you need access to. For more information about these plans, see the Qiskit Runtime plans topic.
- Lite: Free simulators-only plan to help you get started with Qiskit Runtime. Learn to use Qiskit Runtime by following our examples and tutorials for one of the pre-built programs available for running circuits efficiently.
- Standard: A pay-as-you-go model for accessing IBM QPUs and simulators. Build your own programs and leverage all the benefits of Qiskit Runtime by running on real quantum hardware, while maintaining access to all of the simulators available to the Lite plan.
Complete the required information, then click Create.

Install or update Qiskit packages

Install or update the following packages in your development environment. They let you create circuits and work with primitive programs with Qiskit Runtime. For detailed instructions, refer to the Qiskit install and setup topic. Periodically check the Qiskit release notes (or rerun these commands) so that you always have the latest version.

You cannot use pip install -U qiskit to upgrade from any Qiskit 0.x version to 1.0 or later. See the Qiskit 1.0 migration guide for details and instructions.

Be sure to run these commands even if you already installed the packages, to ensure that you have the latest versions.

# Installs the latest version of the Qiskit meta-package for circuit creation.
pip install qiskit -U

# Installs the latest version of the Qiskit Runtime package, which is needed to interact with the Qiskit Runtime primitives on IBM Cloud.
pip install qiskit-ibm-runtime -U

Authenticate to the service

To authenticate to the service, call QiskitRuntimeService with your IBM Cloud API key and the CRN:

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(channel="ibm_cloud", token="<IBM Cloud API key>", instance="<IBM Cloud CRN>")

Find your access credentials

Find your API key. From the API keys page, view or create your API key, then copy it to a secure location so you can use it for authentication.
Find your Cloud Resource Name (CRN). Open the Instances page and click your instance. In the page that opens, click the icon to copy your CRN. Save it in a secure location so you can use it for authentication.

Optionally save your credentials to disk

Optionally save your credentials to disk (in the $HOME/.qiskit/qiskit-ibm.json file). If you don't save your credentials to disk, you must specify your credentials every time you start a new session.

If you save your credentials to disk, you can use QiskitRuntimeService() in the future to initialize your account.

from qiskit_ibm_runtime import QiskitRuntimeService

# Save account to disk and save it as the default.
QiskitRuntimeService.save_account(channel="ibm_cloud", token="<IBM Cloud API key>", instance="<IBM Cloud CRN>", name="account-name", set_as_default=True)

# Load the saved credentials
service = QiskitRuntimeService(name="account-name")

If you need to update your saved credentials, run save_account again, passing in overwrite=True and the updated credentials.

For instructions to use the cloud Quantum Qiskit API, see the authentication section in the API documentation.

Test your setup

Run a simple circuit using Sampler to ensure that your environment is set up properly:

from qiskit import QuantumCircuit
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler

# Create empty circuit
example_circuit = QuantumCircuit(2)
example_circuit.measure_all()

# You'll need to specify the credentials when initializing QiskitRuntimeService, if they were not previously saved.
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

sampler = Sampler(backend)
job = sampler.run([example_circuit])
print(f"job id: {job.job_id()}")
result = job.result()
print(result)

Run a program

Qiskit Runtime uses primitive programs to interface with quantum computers. The following programs are publicly available. To learn more about the changes in the V2 primitives, read Migrate to the V2 primitives

Sampler: Allows a user to specify a circuit as an input and then return the outputs (bitstrings) from every shot (V2), or quasiprobabilities (V1). This enables users to more efficiently evaluate the possibility of multiple relevant data points in the context of destructive interference.
Estimator: Allows a user to specify a list of circuits and observables and selectively group between the lists to efficiently evaluate expectation values and variances for a given parameter input. It is designed to enable users to efficiently calculate and interpret expectation values of quantum operators that are required for many algorithms.

This example uses the Sampler primitive:

# Prepare the input circuit.
from qiskit import QuantumCircuit

bell = QuantumCircuit(2)
bell.h(0)
bell.cx(0, 1)
bell.measure_all()

# Execute the circuit
from qiskit_ibm_runtime import SamplerV2 as Sampler
from qiskit_ibm_runtime.fake_provider import FakeManilaV2

# Run the sampler job locally using FakeManilaV2
backend = FakeManilaV2()

from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_bell = pm.run(bell)

sampler = Sampler(backend)

job = sampler.run([(isa_bell,)])
result = job.result()

pub_result = result[0]
# Get counts from the classical register "meas".
print(f" >> Counts for the meas output register: {pub_result.data.meas.get_counts()}")

ISA input

To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the QPU (referred to as instruction set architecture (ISA) circuits and observables) before being submitted to the Qiskit Runtime primitives. See the transpilation documentation for instructions to transform circuits.

This change has the following important impacts:

Because transpilation is done to match the circuits available on a specific backend, you must specify a backend. If you don't specify a backend, you will receive an error.

Previously, if you did not specify a backend, the least busy QPU that you have access to was used. To use the least busy QPU now, use code similar to this: backend = service.least_busy(operational=True, simulator=False).
The primitives will no longer perform layout or routing operations. Consequently, transpilation options referring to those tasks will no longer have any effect. Users can still request that the primitives do no optimization of input circuits by using optimization_level=0.

Example code for generating ISA circuits and observables:

from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager

# Create a new circuit with two qubits (first argument) and two classical
# bits (second argument)
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

# Set up six different observables.
observables_labels = ["ZZ", "ZI", "IZ", "XX", "XI"]

from qiskit.quantum_info import SparsePauliOp
observables = [SparsePauliOp(label) for label in observables_labels]

# Convert to an ISA circuit and layout-mapped observables.
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(qc)
observables = [
    observable.apply_layout(isa_circuit.layout) for observable in observables
]

Next steps

View the API reference.
Learn about IBM Quantum Computing.