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.txtThen 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 pattern | Migration direction | What to verify |
|---|---|---|
qiskit.execute(...) | Transpile explicitly, then call backend.run(...) | Shots, backend options, and result access |
Legacy Sampler or Estimator | Use the current V2 primitive supplied by the local or provider package | Input tuples, options, and result container fields |
IBMQ-style provider imports | Use the provider package and authentication flow documented for the installed release | Account loading, backend selection, and runtime mode |
QuantumInstance | Move to primitives or an explicit backend workflow | Transpilation, shots, resilience, and measurement handling |
assemble-centered job submission | Pass circuits or primitive inputs through the supported interface | Whether provider-specific options moved |
| Direct counts assumptions | Read the returned result object according to its primitive | Register 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:
- Build and measure a Bell-state circuit.
- Run one local simulator job and normalize its counts.
- Run one sampler and one estimator smoke test if your application uses them.
- Transpile a representative circuit and compare resource metrics.
- 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.