Upgrading a quantum software project is less about changing one package than preserving behavior across circuits, transpilers, simulators, providers, notebooks, and classical optimization code. This practical quantum SDK compatibility guide gives you a repeatable migration checklist for Qiskit, Cirq, PennyLane, Python environments, and common integrations—without relying on a fragile list of version numbers.
Overview
Quantum frameworks evolve quickly, and compatibility is usually a matrix rather than a single yes-or-no result. A project may run successfully with one Python release, simulator, and provider while failing after a seemingly minor change to an execution primitive, observables interface, plugin, or notebook dependency.
For that reason, treat every upgrade as a controlled software migration. Record the working environment, identify the interfaces your project actually uses, make changes in a separate branch, and compare results before and after the upgrade. The goal is not merely to make imports succeed. The goal is to confirm that circuit construction, compilation, execution, measurement, gradients, serialization, and optimization still mean what your code expects.
A compatibility record worth keeping
Keep a small machine-readable record in the repository. At minimum, include:
- Python version and operating-system assumptions.
- Direct quantum SDK dependencies and their pinned or bounded versions.
- Important transitive packages, such as numerical, plotting, notebook, and optimization libraries.
- Simulator backends and provider clients used by tests or production jobs.
- Hardware targets, if the project submits jobs to a provider.
- Notebook, serialization, and data-file formats.
- Known deprecations, workarounds, and intentionally unsupported combinations.
Use the framework's current installation and migration documentation to verify supported combinations before editing this record. A static compatibility table becomes misleading when it presents old ranges as universal guarantees.
Compatibility matrix template
| Layer | Record | Verify during migration |
|---|---|---|
| Python | Interpreter version and environment manager | Supported by every direct dependency, including notebook and optimization tools |
| Qiskit | Core packages, execution APIs, transpilation options, provider client | Release notes, removed or renamed APIs, backend configuration, result objects |
| Cirq | Cirq package, Google or third-party integrations, simulator | Moment and operation behavior, measurement results, serialization, provider adapters |
| PennyLane | Core package, device plugin, interface, differentiation method | Device support, wire conventions, gradient behavior, interface versions |
| Simulators | Local simulator, accelerator library, precision settings | Noise models, shot handling, seeds, state-vector or tensor conventions |
| Providers | Client library, account configuration, target name | Authentication, submission API, transpilation assumptions, job and result formats |
| Integrations | Jupyter, cloud SDKs, optimizers, data pipelines | Import paths, serialization, asynchronous jobs, callbacks, and plotting |
Checklist by scenario
Scenario 1: Upgrading an existing Qiskit project
- Freeze the baseline. Export the current environment and save representative circuit outputs, transpiled circuits, metadata, and optimizer results. Do not rely on a notebook's visible output alone.
- Inventory imports and execution paths. Search the repository for circuit classes, backend selection, transpilation, primitives, provider clients, visualization, and result-parsing code. Include notebooks and examples that may not be covered by unit tests.
- Read migration notes before changing code. Look specifically for deprecated execution patterns, altered result structures, changed default options, backend configuration changes, and removed convenience imports.
- Upgrade in a clean environment. Create a new virtual environment or lockfile revision. Avoid debugging a mixed environment in which old and new packages remain installed together.
- Replace APIs deliberately. Update one interface at a time and add a small test around the replacement. A successful import does not prove that shots, observables, or metadata are interpreted the same way.
- Run circuit-level tests. Start with identity circuits, basis-state preparation, single-qubit gates, controlled gates, measurements, parameter binding, and a small entangled circuit.
- Compare results under fixed conditions. Use fixed seeds where supported, the same shot count, matching precision, and an explicitly chosen simulator. Compare distributions with a tolerance rather than demanding identical sampled strings.
For import failures, backend errors, and result-shape problems, pair this process with the troubleshooting steps in Common Qiskit Errors and How to Fix Them.
Scenario 2: Migrating a Cirq project
- Record the circuit's qubit type, moment structure, gate operations, measurement keys, and serialization format.
- Check whether the project depends on a simulator-specific feature or a provider integration rather than Cirq core alone.
- Test measurement-key names and result access explicitly. Small changes in labeling or result handling can silently alter downstream analysis.
- Compare circuit diagrams and operation counts before comparing performance.
- Run a deterministic test set first, then test sampled execution with several shot counts.
If you are moving between frameworks rather than only upgrading Cirq, document wire ordering, parameter conventions, measurement labels, and gate definitions. The practical differences described in Qiskit vs Cirq are especially relevant during a port.
Scenario 3: Upgrading PennyLane or a device plugin
- Record the PennyLane interface used by the project and whether gradients are computed by backpropagation, parameter-shift, finite differences, or another method.
- Confirm that the selected device supports the operations, observables, shots configuration, and differentiation method required by each test.
- Test wire labels and ordering. A circuit can produce plausible values while applying data to unintended wires.
- Compare both forward results and gradients. Matching expectation values do not guarantee matching derivatives.
- Test hybrid training loops with a small fixed dataset before running a full optimization job.
Projects using variational algorithms should preserve an end-to-end test, not just a device smoke test. A small VQE workflow is a useful model because it exercises circuit construction, expectation values, gradients, and a classical optimizer together.
Scenario 4: Reproducing an older notebook or experiment
- Do not begin by upgrading everything. First try to recreate the original environment from its lockfile, requirements file, container, or recorded metadata.
- Capture the original Python version, SDK versions, simulator settings, random seeds, shot count, and input data.
- Run the notebook from a clean kernel in execution order. Hidden state and stale variables can disguise compatibility problems.
- Only after reproduction succeeds should you create a separate migration branch.
- Save both the legacy and migrated outputs, along with an explanation of any expected numerical differences.
What to double-check
Behavior that can change without an obvious error
- Qubit and wire ordering: Confirm how basis states, bit strings, tensor axes, and plotted circuits are ordered.
- Shots and exact simulation: Distinguish an exact state or expectation value from a sampled estimate. Ensure the same shot setting is passed through every layer.
- Randomness: Identify every source of randomness, including circuit sampling, noise, initialization, and classical optimizers.
- Parameter binding: Test parameter names, ordering, broadcasting, and the shape of batched inputs.
- Gradients: Validate gradient values and shapes independently from the objective function.
- Transpilation: Compare basis gates, depth, two-qubit gate count, layout, and inserted measurements. A logically equivalent circuit may have different hardware costs.
- Noise and precision: Check whether a simulator or plugin changed its noise model, numerical precision, device options, or unsupported-operation behavior.
- Provider boundaries: Separate local tests from provider tests. Authentication, queueing, target availability, and remote result formats should not determine whether core circuit logic passes.
- Serialization: Test saved circuits, pickled objects, JSON data, and notebook outputs after the upgrade rather than assuming old artifacts remain readable.
For quantitative validation, use a defined comparison plan covering accuracy, runtime, memory, circuit depth, gate counts, and result stability. The measurement ideas in How to Benchmark a Quantum Circuit can help turn a vague regression check into a repeatable experiment.
Environment and dependency checks
Prefer a clean environment, a lockfile or constraints file, and a documented installation command. Distinguish direct dependencies from transitive dependencies, and avoid upgrading unrelated packages in the same change unless the project requires it. Record the package manager and resolver used to create the environment so another developer can reproduce it.
For team projects, add a smoke-test job to continuous integration. It should install from the declared dependency files, import the main SDK paths, construct a small circuit, execute it on a local simulator, and validate the result structure. Keep provider tests separate when they require credentials or remote resources.
Common mistakes
- Pinning only the top-level SDK: A framework pin does not constrain provider clients, plugins, numerical libraries, or notebook packages that may affect execution.
- Testing imports instead of behavior: Import success says little about measurements, gradients, transpilation, or result parsing.
- Comparing sampled outputs as exact values: Two statistically valid runs can produce different bit-string counts. Compare distributions with an appropriate tolerance.
- Ignoring defaults: Defaults for shots, optimization, layouts, precision, or device options may change. Set important options explicitly in tests.
- Editing notebooks in place: A notebook that appears fixed may still contain stale outputs or hidden state. Execute it from a clean kernel and review the diff.
- Changing circuit logic and dependencies together: Separate migration changes from algorithm changes so failures remain diagnosable.
- Assuming simulator equivalence: Different simulators can use different conventions, supported operations, noise behavior, and numerical methods.
- Skipping deprecation warnings: Warnings are migration work that has been scheduled for you. Turn them into tracked tasks before they become removal errors.
- Using a remote backend as the first test: Start locally, then validate provider submission separately. This keeps environment failures distinct from account or service failures.
When to revisit
Revisit this checklist before planned dependency upgrades, when Python or notebook environments change, after a provider client update, when a simulator or device plugin is replaced, and whenever a project is transferred to a new team. It is also worth repeating after a long period without maintenance, before reproducing a published experiment, or when results change without an intentional circuit modification.
Keep the compatibility record close to the code and update it whenever the workflow changes. At each review, confirm the framework's official release notes and installation guidance rather than copying an old version table forward. Mark the review date, tested combinations, unresolved warnings, and the next upgrade boundary.
A practical final pass
- Create a clean environment from the project's declared files.
- Run import, circuit, measurement, gradient, and serialization smoke tests.
- Compare representative outputs with fixed settings and documented tolerances.
- Inspect transpiled circuits and provider-specific options.
- Run notebooks from clean kernels and review generated artifacts.
- Record API replacements, warnings, unsupported combinations, and rollback steps.
- Merge only after the migration is reproducible by another developer.
That final record turns a one-time upgrade into maintainable quantum developer tooling. It also gives the next contributor a clear answer to the question that causes most migration delays: which parts of this quantum computing project are actually compatibility-sensitive?