Upgrading a quantum software project is more than changing a version number. This reusable quantum SDK migration checklist shows how to update Qiskit, Cirq, or PennyLane while protecting circuit behavior, measurement semantics, backend access, test results, and rollback options.
Overview
Quantum frameworks evolve quickly. An upgrade may replace deprecated imports, change primitive or device interfaces, alter transpilation defaults, expose new backend options, or require a different way to request measurements. These changes can be correct improvements and still produce unexpected results in an inherited codebase.
The safest approach is to treat a migration as a controlled software change. First record what the current project does. Then create an isolated environment, read the framework’s migration guidance, update one dependency group at a time, and compare old and new behavior with a fixed test set. Do not assume that a circuit that runs successfully is producing equivalent output.
The framework determines the shape of the migration. Qiskit projects often require attention to circuit construction, transpilation, primitives, result objects, and IBM Quantum or other backend interfaces. Cirq projects should be checked for changes to circuit moments, simulators, samplers, resolvers, and device-specific execution. PennyLane projects need particular care around device declarations, QNodes, interfaces to classical machine-learning libraries, transforms, gradients, and measurement return values.
| Framework | Migration areas to inspect | Useful baseline |
|---|---|---|
| Qiskit | Imports, primitives, transpilation, backend configuration, result handling, measurement counts | Transpiled circuits, sampled distributions, expectation values, and runtime logs |
| Cirq | Moment structure, simulator or sampler calls, parameter resolution, qubit ordering, serialization | Final circuit diagram, parameter values, sampled results, and state or expectation checks |
| PennyLane | Device API, QNode signatures, transforms, differentiation, interface settings, measurement shapes | Forward outputs, gradient values, parameter shapes, and training-loss traces |
Checklist by scenario
Before any SDK upgrade
- Capture the current environment. Save the language version, operating-system details, SDK versions, plugins, provider packages, notebook dependencies, and hardware or simulator configuration.
- Pin the known-good state. Record an exact lockfile or requirements file. Keep the current environment available until the migration passes its acceptance tests.
- Freeze representative inputs. Store small circuits, parameter values, random seeds where supported, observable definitions, shot counts, and backend options. A compact fixture is easier to compare than a full production workload.
- Run a baseline. Save circuit diagrams, transpiled outputs, measurement distributions, expectation values, gradients, execution metadata, and failure logs. Include both deterministic tests and sampled tests.
- Read deprecation notices before editing code. Identify APIs scheduled for removal, replacement primitives, changed device interfaces, and compatibility notes for plugins or cloud backends.
When updating a Qiskit project
- Search the repository for deprecated imports and older execution patterns rather than fixing only the first error reported by the interpreter.
- Review the distinction between circuit construction, transpilation, execution, and result interpretation. A changed default in any one layer can affect depth, gate choice, qubit mapping, or output format.
- Check primitive calls and result access carefully. Confirm whether the project expects samples, quasi-probabilities, expectation values, or another result representation.
- Compare transpiled circuits on a fixed target. Inspect depth, two-qubit operations, measurements, layout, and routing decisions instead of comparing only final scores.
- Test local simulators and remote backends separately. Authentication, backend options, shot settings, and runtime configuration should not be hidden inside circuit tests.
When updating a Cirq project
- Print or serialize representative circuits before and after migration. Check moment order, inserted measurements, qubit identity, and parameter resolution.
- Verify whether the project uses a simulator, sampler, custom device, or provider-specific service. Each execution path may expose different compatibility issues.
- Test result shapes and key names. Code that indexes a measurement array positionally can silently break when measurement keys or qubit ordering change.
- Repeat tests with symbolic parameters and resolved numeric values. Parameter-sweep behavior should be compared independently from single-circuit execution.
When updating a PennyLane project
- Confirm that device declarations, wire labels, shots, and supported operations still match the project’s assumptions.
- Check QNode outputs for scalar, vector, and multi-measurement circuits. Measurement shape changes can break optimizers even when the circuit executes.
- Test the selected differentiation method and interface. Compare gradients numerically or against a stored tolerance rather than checking only that training starts.
- Review transforms and compilation steps. A transform may change circuit structure, measurement handling, or supported gradient paths.
- Run a short training fixture and compare loss direction, parameter updates, and final output against the baseline.
When moving to a different backend
- Separate SDK migration from backend migration where possible. Change one variable at a time.
- Record native gates, connectivity, supported measurements, shot behavior, noise settings, queue or execution options, and qubit mapping assumptions.
- Compare simulator results with hardware results using appropriate tolerances. Hardware output should not be treated as a failed software migration without accounting for noise and sampling.
What to double-check
Measurement semantics: Confirm whether results represent counts, probabilities, expectation values, samples, or tensors. Check bit order, wire labels, endianness assumptions, shot counts, and the treatment of unmeasured qubits.
Randomness and reproducibility: A seed may control only part of an execution path. Record simulator seeds, circuit-generation seeds, parameter initialization, and backend settings separately. Compare distributions with a stated tolerance instead of demanding identical samples.
Transpilation and compilation: A functionally equivalent circuit may have a different depth or gate set. Store pre-transpilation and post-transpilation representations, and monitor resource metrics that matter to the project.
Classical interfaces: Hybrid AI-quantum workflows can fail at the boundary between quantum outputs and classical code. Check tensor types, gradients, device placement, batch dimensions, serialization, and conversion between arrays and framework-specific objects.
Compatibility boundaries: Test the SDK together with provider plugins, visualization packages, notebook integrations, and experiment-tracking tools. A core package upgrade does not guarantee that every surrounding package accepts the same objects.
Use a short upgrade record for every migration:
Project and owner:
Previous environment:
Target environment:
Changed packages:
Deprecations addressed:
Baseline fixtures:
Behavioral differences:
Accepted tolerances:
Backend checks:
Rollback command or lockfile:
Follow-up documentation:Common mistakes
- Upgrading everything at once: If the SDK, Python version, provider plugin, and numerical libraries change together, diagnosing the cause becomes unnecessarily difficult.
- Testing only successful execution: A circuit can run while returning a differently shaped result, using a different qubit order, or applying a different compilation path.
- Comparing only a final model score: In a hybrid workflow, a similar score can hide changed gradients, convergence speed, resource use, or backend behavior.
- Ignoring notebooks and examples: Production code may pass while tutorial cells, serialized circuits, or scheduled jobs still depend on removed APIs.
- Removing compatibility code too early: Keep a small, documented migration layer when multiple environments must be supported. Delete it only after the support boundary is explicit.
- Skipping rollback planning: Preserve the previous lockfile, container, or environment and define how to restore it before deploying the upgrade.
For failures that appear unrelated to the version change, use a focused debugging process. The quantum circuit debugging checklist can help isolate import, measurement, device, and execution problems. For performance comparisons, pair migration tests with a structured quantum circuit benchmarking workflow.
When to revisit
Revisit this checklist before each planned dependency-maintenance cycle, after a major SDK release, when a deprecation warning appears, or when a project changes simulator, provider, cloud platform, or hardware target. It is also useful when inheriting an older quantum codebase: establish a baseline before modernizing it.
Maintain a small compatibility note in the repository. Include the supported environment, pinned dependencies, known backend limitations, migration decisions, and the date of the last successful validation. Review it during seasonal planning cycles and whenever the workflow changes from circuit experimentation to production scheduling, hybrid AI training, or hardware execution.
The practical sequence is simple: create a branch, pin the old state, capture behavior, read the migration notes, upgrade one boundary at a time, run deterministic and statistical tests, inspect compiled circuits and measurements, update documentation, and keep rollback artifacts until the new environment has survived a normal workload. That discipline makes quantum SDK migration a repeatable engineering task rather than a trial-and-error rewrite.
For broader maintenance planning, track framework changes in a quantum API and SDK release tracker, and document reproducible experiments using the guidance in Quantum Computing with Jupyter Notebooks.
