Qiskit 2.x Migration Guide: Update Circuits, Primitives, Transpilation, and Backend Code
QiskitPythonAPI migrationQuantum softwareTranspilationQuantum developer tools

Qiskit 2.x Migration Guide: Update Circuits, Primitives, Transpilation, and Backend Code

UUpQbit Labs
2026-11-13
7 min read

A practical Qiskit 2.x migration checklist covering circuits, primitives, transpilation, backends, results, packaging, and tests.

This Qiskit 2.x migration guide gives you a practical, repeatable way to upgrade an existing project: audit dependencies, modernize circuits and primitives, update transpilation and backend code, then verify results with focused tests. The examples use stable migration patterns while leaving provider-specific details for the release documentation of the Qiskit packages you install.

Overview

A Qiskit upgrade is rarely just an import change. A project may combine circuit construction, transpilation, backend selection, job submission, result parsing, visualization, notebooks, and provider-specific packages. Each layer can have a different compatibility boundary.

Start by recording the versions currently used in the repository:

python -m pip show qiskit qiskit-aer qiskit-ibm-runtime
python -m pip freeze > requirements-before.txt

Then create a clean branch and a fresh virtual environment. Do not upgrade a working production or teaching environment in place before you have a reproducible test run. Pin or constrain dependencies deliberately, and check the release notes for the exact Qiskit, Python, simulator, and provider versions relevant to your target environment.

The main migration principle is to separate four concerns:

  • Circuits: operations, measurements, parameters, and observables.
  • Compilation: mapping a circuit to a backend’s instruction set and topology.
  • Execution: selecting a simulator or hardware service and submitting work.
  • Results: extracting counts, samples, expectation values, or metadata.

This separation makes failures easier to diagnose. A circuit can remain valid while its execution primitive changes, and a job can complete successfully while result parsing silently returns the wrong data structure.

Checklist by scenario

1. Updating a basic circuit and simulator workflow

Older tutorials often use execute as a convenience function. A modern workflow makes transpilation and submission explicit:

from qiskit import QuantumCircuit, transpile
from qiskit_aer import AerSimulator

circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure([0, 1], [0, 1])

backend = AerSimulator()
compiled = transpile(circuit, backend=backend)
job = backend.run(compiled, shots=1024)
result = job.result()
counts = result.get_counts()
print(counts)

This pattern is easier to test than a hidden execution helper. It also gives you a clear place to add an optimization level, a seed where supported, or backend-specific options. Keep simulator imports separate from the core Qiskit package; optional providers and simulators may have their own release cycle.

2. Migrating from legacy Sampler usage

Primitive APIs have evolved from earlier V1-style interfaces toward V2 interfaces. The exact class depends on whether you are using a local primitive or a cloud provider. For a local statevector-oriented test, a representative pattern is:

from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler

circuit = QuantumCircuit(1)
circuit.h(0)
circuit.measure_all()

sampler = StatevectorSampler()
result = sampler.run([circuit], shots=1024).result()
pub_result = result[0]
print(pub_result.data)

Do not copy this result access pattern into every provider integration without checking its object model. V2 primitives commonly return structured publication results, and the data container may expose named classical registers or sampler-specific fields rather than a direct legacy counts dictionary.

For IBM Quantum Runtime projects, use the primitive classes supplied by the installed qiskit-ibm-runtime version and follow that package’s current examples. A typical migration task is replacing a legacy Sampler or Estimator import with its V2 counterpart, then adapting options, mode, and result handling together. Treat those as one change, not three unrelated edits.

3. Migrating Estimator workflows

Estimator code usually needs more than a class-name replacement because modern interfaces commonly accept circuits and observables as publication inputs. Keep the observable explicit and test its expectation-value shape:

from qiskit import QuantumCircuit
from qiskit.quantum_info import SparsePauliOp
from qiskit.primitives import StatevectorEstimator

circuit = QuantumCircuit(1)
circuit.h(0)
observable = SparsePauliOp.from_list([("Z", 1.0)])

estimator = StatevectorEstimator()
result = estimator.run([(circuit, observable)]).result()
print(result[0].data.evs)

The exact result fields can differ between local and remote implementations. Assert values and dimensions in tests instead of relying on printed representations.

4. Updating transpilation and backend selection

Prefer an explicit backend object and compile at the boundary where execution is selected:

from qiskit import transpile

compiled = transpile(
    circuit,
    backend=backend,
    optimization_level=1,
)

For provider backends, select the backend through the provider’s current API, then pass that object to transpile. Avoid hard-coding a backend name throughout circuit-building code. A small factory or configuration layer lets CI use a simulator while a deployment environment uses a selected hardware target.

When comparing pre- and post-migration behavior, record at least the number of qubits, gate depth, and operation counts. A change in transpilation settings can alter those metrics even when the logical circuit is unchanged. See Quantum Circuit Resource Estimation in Python for a practical way to inspect circuit resources.

Compatibility checklist for common migrations

Older patternMigration directionWhat to verify
qiskit.execute(...)Transpile explicitly, then call backend.run(...)Shots, backend options, and result access
Legacy Sampler or EstimatorUse the current V2 primitive supplied by the local or provider packageInput tuples, options, and result container fields
IBMQ-style provider importsUse the provider package and authentication flow documented for the installed releaseAccount loading, backend selection, and runtime mode
QuantumInstanceMove to primitives or an explicit backend workflowTranspilation, shots, resilience, and measurement handling
assemble-centered job submissionPass circuits or primitive inputs through the supported interfaceWhether provider-specific options moved
Direct counts assumptionsRead the returned result object according to its primitiveRegister names, bit order, and data shape

This table is a migration map, not a substitute for release-specific documentation. APIs can be deprecated in one package while remaining available in another compatibility layer.

What to double-check

  • Imports and package boundaries: confirm whether a class belongs to qiskit, qiskit-aer, a provider package, or an optional add-on.
  • Python compatibility: check the target Qiskit release and every provider or simulator against the Python version used by local development and CI.
  • Bit ordering: compare a known Bell-state result before and after migration. Do not assume that a changed display format means the circuit changed.
  • Parameterized circuits: verify parameter binding, parameter order, and the shape of submitted parameter values.
  • Transpilation: compare the target instruction set, coupling map, optimization level, depth, and two-qubit gate count.
  • Primitive semantics: check shots, observables, error or resilience options, and whether results are sampled or computed by a statevector simulator.
  • Tests: test logical behavior rather than exact transpiled instruction sequences unless the sequence itself is the requirement.
  • Packaging: rebuild the environment from a lockfile or requirements file instead of depending on packages left in a developer’s global installation.

For SDK selection context, compare the execution model with other tools in Comparing Quantum SDKs: Qiskit, Cirq, PennyLane, Amazon Braket and Azure Quantum.

Common mistakes

Changing every layer at once. Upgrade the environment first, then repair imports, then run circuit tests, then migrate execution and result parsing. Small commits make regressions traceable.

Assuming a deprecated method is the only issue. A replacement primitive may use a different input and output model. Read the method signature and write a small smoke test before updating a larger application.

Testing only notebook output. Notebooks can hide state, cached imports, and manually installed packages. Run the same workflow as a script or automated test in a clean environment.

Comparing raw result objects. Object representations and metadata may change between releases. Compare normalized counts, expectation values, dimensions, and tolerances instead.

Mixing provider generations. Keep local simulator examples and cloud runtime examples in separate modules where possible. This prevents provider authentication or options from leaking into unit tests.

Trusting an old tutorial without checking its environment. Record the tutorial’s imports and assumptions, then map them to the installed Qiskit release. A tutorial can still explain the algorithm correctly while using an obsolete submission API.

When to revisit

Revisit this checklist before a major Qiskit upgrade, when CI changes its Python version, when a simulator or cloud provider package is upgraded, or when a previously working tutorial begins producing import or result errors. It is also worth reviewing before a seasonal planning cycle if your team schedules dependency updates or hardware experiments at that time.

Keep a short migration record in the repository containing the previous and target versions, release-note links, changed imports, primitive choices, backend configuration, and test results. On every quarterly dependency review, run a small validation suite:

  1. Build and measure a Bell-state circuit.
  2. Run one local simulator job and normalize its counts.
  3. Run one sampler and one estimator smoke test if your application uses them.
  4. Transpile a representative circuit and compare resource metrics.
  5. Build the environment from scratch in CI.

Finally, update your project’s own examples as part of the migration. A current README, pinned environment, and result-parsing test will prevent the next upgrade from becoming a search through outdated snippets. For broader comparisons between Qiskit, Cirq, and PennyLane, consult Qiskit vs Cirq vs PennyLane: Choosing the Best Quantum SDK.

Related Topics

#Qiskit#Python#API migration#Quantum software#Transpilation#Quantum developer tools
U

UpQbit Labs

Quantum Software Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.