Today, we’re excited to announce the release of Qiskit SDK v2.1! The first minor release of the Qiskit SDK v2.x series brings performance improvements and exciting new capabilities designed to enable near-term demonstrations of quantum advantage.
The dawn of quantum advantage is fast approaching, and we predict the world will have incontrovertible proof of practical quantum advantage by the end of 2026. Continued collaboration between the quantum and high-performance computing (HPC) communities will play an essential role in making that happen, which is why we’ve focused so much of our recent development efforts on extending the Qiskit SDK’s C API support.
As we explained in the Qiskit SDK v2.0 release summary, C is a foundational programming language that has given rise to a very mature ecosystem of libraries and tools. It isn’t the most widely used programming language in classical HPC, but — unlike Python — it offers extensive interoperability with other programming languages, including popular HPC programming languages like C++ and Fortran. This means the new C API will allow researchers to integrate Qiskit into HPC experiments with greater ease and flexibility than ever before, and it will eventually enable the community to build a much broader ecosystem on top of Qiskit that is independent of any one programming language.
Below, we’ll show you how the latest updates to Qiskit’s C API enable high-performance construction of quantum circuits designed for performance-critical applications in HPC environments. We’ll also take a deep dive into key performance enhancements you’ll be getting with the v2.1 release, which include significant improvements in multi-controlled gate synthesis.
The TL;DR
The biggest updates we’re going to cover in this article include the following:
- Extended C API support: Developers can now build quantum circuits and targets using a C API, which is already capable of improving the performance of circuit-build time.
- Transpiler improvements: Passes in the preset manager have been reconfigured such that the transpiler can now automatically recognize when a given target is using a discrete Clifford+T basis.
- Improved synthesis algorithms: Performance improvements in circuit synthesis serve to reduce gate counts, circuit depth, and resource usage.
- Tools for multi-controlled gates: New synthesis algorithms and plugins give you greater flexibility in working with multi-controlled gates.
boxinstruction enhancements: Theboxinstruction now supports annotations and stretch delays for more expressive timing control.
A note for Qiskit SDK v1.x users
We understand that not everyone has had a chance to update to the v2.x series yet. If you are still using Qiskit SDK v1.x, we recommend you update to v1.4, which it is fully backwards compatible with the Qiskit v1 series.
Those using Qiskit v1.4 will have bugfix support until at least the end of September, and security support until March 2026. You can use that time to clean all your deprecation warnings and move to Qiskit v2.x. For reference, be sure to have a look at the migration guides here.
Top New Features & Improvements
In this section we’ll cover some of the most important new features and enhancements included in this release. If you want to learn more about these or other features that didn’t make it into this article, you can see the full list of new features here.
Expanded C API support for quantum circuit construction
One of the most exciting new features in Qiskit v2.1 arrives via the expanded C API, which now enables developers to construct quantum circuits directly in C. Future releases will give you the ability to transpile circuits. In the meantime, let’s take a look at one of the use cases where this most recent expansion of the Qiskit SDK’s C API really shines: high-performance circuit construction.
With the new C API, circuits that might take several milliseconds to construct in Python can now be built in a fraction of that time — just a few hundred microseconds. Case in point: constructing a 1000-qubit GHZ state is approximately 10-20x faster when mixing C and Python compared to the fastest pure Python.
Let’s walk through how to do that. You’ll start by writing a function in C that takes the number of qubits and returns a Python object coming from qk_circuit_to_python:
Once this file is compiled as, say build_ghz.so, you can call it from Python using ctypes. You can then use that function in your Python environment to run things more quickly. The GHZ state builder we’ve just created in C is equivalent to the following Python implementation, but much faster!
You can build circuits in C with all the standard Qiskit gates and instructions, such us measure, delay, reset, and barrier. This also includes the UnitaryGate, an arbitrary gate defined solely by its unitary matrix. You can find an example of this in our C API documentation:
For now, the Qiskit SDK C API only supports Qiskit operations defined in the Rust data model. In future releases, we plan to move even more of the Qiskit SDK’s core functionality to Rust, which will give us the ability to expose a C API for additional operations.
The most important takeaway is that you can now build quantum circuits in C. When needed, you can easily pass these circuits back into Python using qk_circuit_to_python(), where it will be treated like any other QuantumCircuit and fully interoperable with Qiskit’s transpiler, visualization tools, and runtime integrations.
Use of the Qiskit C API from a Python extension is just the start. Future releases aim to support full workflows in C.
Transpiler support for Clifford+T targets
We have improved the default behavior of the generate_preset_pass_manager() function. Now, Qiskit will detect whether the target is comprised solely of Clifford and T gates and generate a pass manager that will be able to decompose the circuit into this discrete basis. This was possible prior to the v2.1 release, but it required manually building a full pass manager. Qiskit v2.1 integrates it fully into the preset pass managers. As an example, consider the code snippet below:
Previously, the generated preset pass manager was not able to decompose single-qubit rotations into Clifford+T gates. To overcome this limitation, it applies the Solovay-Kitaev decomposition to approximate single-qubit rotation gates using H, T, and Tdg gates. It also calls the BasisTranslator transpiler pass to further translate the gates into the target basis set. Beyond that, the new pass manager introduces additional changes such as the pass OptimizeCliffordT and improvements in the definition attribute of several standard gates — all designed to enable a more efficient translation into Clifford+T gates.
It is important to note that the specified Clifford+T basis gate set should be universal. Otherwise, transpilation might not succeed. While the gate set [‘h’, ‘t’, ‘tdg’] or even [‘h’, ‘t’] is sufficient for universality, best practice is to add more Clifford gates to the set if possible. Otherwise, the translation might be less efficient. For example, not including the S-gate might trigger decomposition of S-gates into pairs of T-gates. In other words, failure to include the right set of Clifford gates could cause Clifford gates to decompose into non-Clifford gates, which may not be the desired behavior.
Improved synthesis algorithms
Qiskit SDK v2.1 brings further performance improvements in circuit synthesis, including new algorithms, plugins, and optimizations that significantly reduce gate counts, circuit depth, and resource usage. These improvements are especially impactful for multi-controlled operations and decomposition of circuits into the Clifford+T basis set.
One of the biggest performance improvements we made was to the SolovayKitaevDecomposition transpiler pass. This transformation pass will decompose arbitrary single-qubit gates into a set of fixed single-qubit gates. In Qiskit v2.1, we have ported this transpiler pass to Rust, leading to a 100x improvement in runtime.
Annotations and stretch delays for boxes
The Qiskit SDK v2.0 release in February introduced a new BoxOp instruction designed to provide more flexibility and transparency in handling tasks like Pauli twirling and error mitigation. The BoxOp in Qiskit is analogous to the box feature in OpenQASM 3.0.
Now, with Qiskit v2.1, we’ve extended the boxes from v2.0 with annotations. Annotations give you the ability to tag boxes with custom data intended for consumption by custom transpiler passes or in later stages of the execution stack. The general concept is that the annotation allows the circuit constructor to provide intent with regard to how that section of the circuit should be interpreted.
For example, the OpenQASM 3 specification illustrates how annotations can be used to prevent swap insertion across a specific code region. With Qiskit v2.1, this behavior can now be expressed directly in the circuit using annotated boxes.
Note, however, that the preset pass manager does not understand the annotation. You can only apply it to custom workflows, meaning you’ll need a custom transpiler pass to recognize this annotation and skip any swap insertion logic within that region, aligning with the intent expressed in OpenQASM 3. For instance:
The module qiskit.qasm3 dumps this circuit as the following:
Additionally, boxes can now accept a duration that leverages stretch variables — another feature introduced in Qiskit v2.0. This makes it easier to ensure that compiled circuits reflect the intended timing of the circuits you design. The actual resolution of the absolute timing is deferred until the execution of the circuit. For more details, take a look at our documentation here.
box annotations and stretch features will play a key role in some of the important changes we’ll soon be making to Qiskit Runtime primitives. Stay tuned for more details on that coming later this year.
New Deprecations and upgrade considerations
In this section, we’ll cover some of the key considerations to keep in mind when upgrading to the v2.1 release — such as new deprecation warnings or changes in supported platforms pursuant to Qiskit’s deprecation policy (documented in full here). For guidance on how to deal with deprecation warnings, check out the deprecations section in our previous blog here. You can see more detail about the deprecations specific to this release here.
Deprecation of Python v3.9
First, we want to remind everyone that support for running Qiskit with Python v3.9 has been deprecated and will be removed in the Qiskit SDK v2.3 release. This is because Python v3.9 will have reached end-of-life by the time the v2.3 release is published. Starting with v2.3, you will need to upgrade your Python version to Python v3.10 or above.
Ongoing circuit library refactoring
The circuit library underwent extensive refactoring in the Qiskit v1.3 release, in an effort to better define and improve the performance of certain operations. These operations are divided into two distinct categories.
On the one hand, we have operations that are defined by the action they perform — for example, a mathematical transformation. These are now defined as Instruction or Gate objects, which may have one or more detached synthesis algorithms that the compiler can reason about during circuit compilation. Examples of this kind of operation include the Quantum Fourier Transform (QFT), Pauli evolutions, arithmetic circuits, and multi-controlled-not (MCX) gates.
On the other hand, there are operations that are circuits which are uniquely defined by their structure, and which possess a well-defined sequence of gates. You can construct these using generic Python functions, returning a QuantumCircuit. Examples of operations in this category include N-local and Quantum volume circuits.
On the other hand, there are operations that are uniquely defined by their structure. Instead, their definition is a well-defined sequence of gates. You can construct these operations using generic Python functions, returning a QuantumCircuit. Examples of operations in this category include N-local and Quantum volume circuits.
The Qiskit v2.1 release continues the process of transitioning objects into one of the two above-mentioned categories, and also marks the official deprecation of a number of QuantumCircuit subclasses. Find the full list in our documentation.
| Class | Status | Suggested alternative |
|---|---|---|
QFT | Deprecated | QFTGate |
MCXGrayCode, MCXRecursive, MCXVChain | Deprecated | MCXGate |
TwoLocal, NLocal | Deprecated | n_local |
EfficientSU2(…) | Deprecated | efficient_su2(…) |
RealAmplitudes(…) | Deprecated | real_amplitudes(…) |
ZZFeatureMap(…) | Deprecated | zz_feature_map(…) |
QuantumVolume(…) | Deprecated | quantum_volume(…) |
EvolvedOperatorAnsatz(…) | Deprecated | evolved_operator_ansatz(…) |
This is a very high-level list, and it should not be considered exhaustive. Please be sure to refer to the Qiskit v2.1 release notes for a comprehensive rundown of deprecated classes with drop-in replacements.
SymEngine and SymPy are now optional dependencies
In Qiskit SDK v2.1, we introduced a new internal symbolic math library built in Rust, which now forms the core of the ParameterExpression class. This means that Qiskit no longer requires the SymEngine or SymPy library as Python dependencies. Previously these libraries were used to build up the ParameterExpression class. SymEngine and SymPy remain as optional dependencies, as there are a few locations where they are still used, but they are no longer core to Qiskit’s functionality.
For reference, SymEngine is only potentially used for deserializing QPY format versions 10, 11, and 12. SymPy, on the other hand, may be needed for deserializing all QPY format versions prior to version 13, as well as a few specific visualization methods and other use cases. If your execution path requires these libraries and you don’t have them installed, an error message will let you know you that a necessary library is missing.
Final notes
And there you have it! The most important details of the latest release. Remember, if you want to put ideas forward for future versions of Qiskit you can always open a GitHub issue to request a feature or report a bug! And if you want to follow what's coming up in the next release you can take a look at the Qiskit Roadmap.
Many people contributed to this release, special thanks to (in alphabetical order):
