Qiskit SDK v1.0 has been available for over a month now, and it’s thrilling to see so many Qiskit developers eagerly making the transition. This release marks the beginning of a new, much more stable era in the history of the Qiskit. It also brings an important shift in the best practices for upgrading to new Qiskit versions.
Moving forward, Qiskit will now follow a release cycle based on the widely-used Semantic Versioning scheme, where software releases are numbered using the “X.Y.Z” or “major.minor.patch” format (e.g., Qiskit’s first major version, Qiskit v1.0.0). If you haven’t yet made the move to Qiskit v1.0, this blog post will tell you everything you need to know to take full advantage of this new system and ensure your transition is a smooth one.
Understanding the new Qiskit release cycle
In the past, each new Qiskit release introduced breaking changes that had the potential to interfere with a user’s code. Those releases occurred fairly often, about once every three months. Qiskit’s new release cycle addresses this problem by making a useful distinction between different types of releases. Qiskit will now publish major releases roughly once per year, minor releases on the traditional schedule of once every three months, and smaller patch releases that implement bug fixes between minor releases as needed.
This new release cycle will help make Qiskit more stable than ever before. The once-per-year major releases will now be the only Qiskit releases that contain breaking changes. In other words, today’s Qiskit v1.0 users won’t have to worry about breaking changes until it’s time to upgrade to Qiskit v2.0. Before that point, only minor and patch releases will be published, and any changes or features that are introduced will be fully backwards compatible.
The new release cycle also provides a full six months of support — including continued publication of new patch releases — for the final minor release of the previous major version. For example, Qiskit v0.46 was the final minor release of the 0.x era. Since Qiskit v1.0 was released in February 15 2024, users will continue to have support for Qiskit v0.46 until August 15, 2024.
Of course, like all software users, Qiskitters don’t always keep perfectly up-to-date with new releases. And for Qiskit developers, that’s often intentional. Because the minor releases of Qiskit’s 0.x era often contained breaking changes, many Qiskit developers have placed a cap on their Qiskit version (e.g. qiskit<0.44) to prevent automatic breaking updates. If you’re one of these developers, you may be thinking about making the jump directly to Qiskit v1.0 from Qiskit v0.45. However, doing so can make your transition much more challenging than it needs to be.
The reason for this is that, although the v0.46 release does not contain any new performance enhancements or features, it does include deprecation warnings for all of the breaking changes that come with the v1.0 release. Many of these warnings are not included in Qiskit v0.45, so it is generally a good practice for those using Qiskit v0.45 to first migrate to v0.46 before changing to v1.0. This is especially true if you are responsible for maintaining a software package that uses Qiskit. The extensive deprecation warnings will help make the transition to Qiskit v1.0 much smoother, and the extended support cycle ensures that you have many more months to migrate.
Best practices for the transition
So, the bottom line is, if you’re a developer depending on Qiskit v0.45 who is planning to transition to Qiskit v1.0 — and especially if you have packages that depend on Qiskit v0.45 — we strongly encourage you to try upgrading to v0.46 first. Pay close attention to the warnings you see in Qiskit v0.46 and take your time cleaning them up. As previously mentioned, you’ll have until August 2024 to migrate your code before Qiskit 0.46 is no longer supported.
Note: If your Qiskit version is currently capped at v0.44 or any release published prior to that, you should consider first updating to Qiskit v0.45, and then to Qiskit v0.46. Additionally, if you’re still dependent on qiskit-terra, consider that the qiskit metapackage only contained qiskit-terra since v0.45. Since then, depending on qiskit directly is the preferred approach, and doing so will ease your journey to v1.0.
Once you’ve cleaned up all your deprecation warnings and feel you are ready to upgrade to Qiskit v1.0, be sure to first test your code with Qiskit SDK v1.0. Next, update your requirements.txt to support Qiskit v1.0, and from there you should be all set. Remember, you will not be able to upgrade an existing Qiskit v0.x installation to Qiskit v1.0 in-place. You’ll have to create a new conda/pip/poetry environment and install qiskit>=1.0 to use the v1.0 release.
Now, if your code is used by many packages or by a relatively large user-base, you may want to consider offering dual support — i.e., writing your code to support both v0.46 and v1.0. For example if your current package is your_package 3.2, you can release your_package 4.0 with Qiskit v1.0 support and your_package 3.3 with Qiskit v0.46 support. Or, alternatively, you can release your_package 4.0 which can be run with Qiskit v0.46 AND Qiskit v1.0.
Let’s take a look at some examples of how this might work in practice. Say you have the following code:
In 0.46, this code will raise the following DeprecationWarnings:
There are two DeprecationWarnings in lines 2 and 12. The first points to the usage of BasicAer. You can replace it with:
The second warning refers to the use of execute. You can fix that by instead using the the Sampler primitive. Here we should replace the call to execute with a call to first transpile the circuit and then executing the sampler.run() method:
The fully migrated code now looks like:
This code raises no warning! You can now safely run it in Qiskit v1.0, and it should work just fine without the need for further changes.
Hopefully, this article will provide a useful resource to those planning their transition to Qiskit v1.0, and will help save Qiskitters from some potential headaches. For more details about Qiskit v1.0, including a detailed look at breaking changes, be sure to read the Qiskit v1.0 release notes and migration guide.
As always, if you want to put ideas forward for future versions of Qiskit, feel free to 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 releases, check out the Qiskit milestones here.
