Skip to main contentIBM Quantum Documentation

Configure runtime compilation for Qiskit Runtime

Runtime compilation techniques optimize and transform your circuit to minimize errors. Runtime compilation adds some classical pre-processing overhead to your overall runtime. Therefore, it is important to achieve a balance between perfecting your results and ensuring that your job completes in a reasonable amount of time.

Primitives let you employ runtime compilation by setting the optimization level (optimization_level option) and by choosing advanced runtime compilation options.


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 system (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. Due to this change, the primitives will no longer perform layout or routing operations; consequently, transpilation options referring to those tasks will no longer have any effect. Users may still request that the Primitives do no optimization of input circuits via options.transpilation.skip_transpilation.

Set the optimization level

The optimization_level setting specifies how much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer compile times.

In current primitive versions, optimization levels 2 and 3 behave identically to level 1.

Optimization LevelEstimator & Sampler

No optimization: typically used for hardware characterization or debugging

  • Basis translation
  • Layout (as specified)
  • Routing (stochastic swaps)
1, 2, 3

Light optimization:

  • Single-qubit gate optimization
  • Two-qubit gate optimization
  • Error suppression: dynamical decoupling

If using an IBM Cloud® Qiskit Runtime service instance with Q-CTRL performance management enabled, there is no need to specify runtime optimization or resilience levels, as the strategy includes an automatic preset.

Q-CTRL defaults to optimization_level=3 and resilience_level=1. Setting optimization_level or resilience_level equal to 0 will result in an execution error. Levels 1, 2, and 3 are permitted but will not impact performance. Setting other options will likewise not impact performance, and it may result in a runtime warning. For more information visit the Q-CTRL documentation(opens in a new tab).

Example: configure Estimator with optimization levels

from qiskit_ibm_runtime import QiskitRuntimeService, Estimator, Options
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.circuit.library import RealAmplitudes
from qiskit.quantum_info import SparsePauliOp
service = QiskitRuntimeService()
backend = service.backend("ibmq_qasm_simulator")
options = Options(optimization_level=1)
psi = RealAmplitudes(num_qubits=2, reps=2)
H = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)])
theta = [0, 1, 1, 2, 3, 5]
pm = generate_preset_pass_manager(backend=backend)
psi =
H = H.apply_layout(psi.layout)
estimator = Estimator (options=options, backend=backend)
job =[psi], observables=[H], parameter_values=[theta])
psi1_H1 = job.result()

If the optimization level is not specified, the service uses optimization_level = 1.

Example: configure Sampler with optimization levels

from qiskit_ibm_runtime import QiskitRuntimeService, Sampler, Options
service = QiskitRuntimeService()
backend = service.backend("ibmq_qasm_simulator")
options = Options(optimization_level=1)
sampler = Sampler(options=options, backend=backend)

Advanced runtime compilation options

Future versions of the primitives will offer options to tune runtime compilation. Currently, the only option with any effect is skip_transpilation (bool), which turns off all optimizations done with the primitives.

Next steps

Was this page helpful?