Qiskit 1.0 packaging changes

Qiskit 1.0 uses a different packaging structure than previous Qiskit versions and might cause problems in environments that use packages that are not ready for Qiskit 1.0.

This guide is divided into the following sections. You only need to review the sections that are relevant to you.

• Users should read the For users section.
• If you develop or maintain a package that depends on Qiskit, read the For developers section.
• If you are interested, review the What is changing and why it changed section.
• If you encounter problems installing or importing Qiskit 1.0, review the Troubleshooting section.

For users

You must start a new virtual environment to install Qiskit 1.0. It is very tricky and error-prone to upgrade an existing installation in-place to Qiskit 1.0.

Create the new environment

1. Create a new virtual environment, using your preferred version of Python 3.8 or later. Use any path you choose in place of /path/to/qiskit-1.0-venv.

   macOS

   Linux

   Windows

   python3 -m venv /path/to/qiskit-1.0-venv

2. Activate the environment.

   macOS

   Linux

   Windows

   source /path/to/qiskit-1.0-venv/bin/activate

3. Install packages as desired. You should do this by using only one pip install command with all the dependencies on it.

   pip install 'qiskit>=1'

   You can optionally include additional packages by including them as arguments. For example:

   pip install 'qiskit>=1' jupyterlab pandas matplotlib

   Qiskit 1.0 includes breaking changes, so several packages are marked as not-yet-compatible with it. Therefore, you might see errors from pip until new versions of those packages are released. Old versions of packages might also depend on the legacy qiskit-terra package. Such packages might not return errors when running this command, but might raise an error when running import qiskit. You should not install any packages that depend directly on qiskit-terra.

   Tip

   One way to require pip to forbid qiskit-terra from individual install commands is to use a constraints file(opens in a new tab) that requires that qiskit-terra is set to an impossible version. For example, a constraints file that includes the line qiskit-terra>=1.0 will mean that if a dependency attempts to install qiskit-terra, no published versions will match the requirements.

   We have provided such a file in a GitHub Gist at https://qisk.it/1-0-constraints(opens in a new tab), which you can use like this:

   pip install -c https://qisk.it/1-0-constraints qiskit [other packages]

   If a package requires qiskit-terra, you will see a resolution failure.

   Caution

   Do not install packages that are incompatible with Qiskit 1.0 on this virtual environment. If you need to use such packages, install them in a separate virtual environment with Qiskit 0.45 or 0.46.

   If you have an existing environment, you can use pipdeptree(opens in a new tab) to query the requirements of your installed packages to see if they require qiskit<1. For any that require qiskit<1, check for updates that make it compatible with Qiskit 1.0.

   If you encounter issues, consult the troubleshooting section, or ask on Qiskit Slack(opens in a new tab). If you think there is a bug, you can create an issue against Qiskit(opens in a new tab).

4. If you are not planning to use the environment immediately, use the deactivate command to leave it.

Use the new environment

Each time you start a new command line session, you must "activate" the environment by running the activate command:

source /path/to/qiskit-1.0-venv/bin/activate

source /path/to/qiskit-1.0-venv/bin/activate

C:\path\to\qiskit-1.0-venv\Scripts\activate.ps1

For developers

If you maintain a package that depends on Qiskit, use this information to learn how to correctly express your compatibility and test against Qiskit 1.0.

Recommendations for requirements

We recommend that your package requires qiskit>=0.45,<1 (or other appropriate lower bound) if you are not certain whether the package is compatible with Qiskit 1.0. This is the same recommendation being made for NumPy 2.0 compatibility.(opens in a new tab)

A Qiskit 1.0 release candidate, version 1.0.0rc1, will be released on 1 February 2024. You should test your package against this, and as soon as possible, release a new (compatible) version of your package with its upper requirement unpinned.

Recommendations for testing against Qiskit 1.0

These recommendations apply to testing proactively against the Qiskit main branch, and to testing against the 1.0.0rc1 (and later, if applicable) release candidate.

We do not recommend initially branch-protecting on CI success against the Qiskit main branch because Qiskit changes could prevent you from merging PRs. After the release of Qiskit release candidates, and after all of your package's dependencies support Qiskit 1.0, we do recommend branch-protecting on success against the latest release candidate, to ensure that the package remains compatible with Qiskit 1.0.

If neither your package, nor any of its transitive dependencies, has a requirement pin on qiskit<1, you should create a testing virtual environment as you normally would, in a single pip install command, and directly specify qiskit==1.0.0rc1 or qiskit==git+https://github.com/Qiskit/qiskit.git@main as appropriate. This is the most reliable way to ensure that you have a completely valid environment.

If the only component of your package's dependency graph that has a requirement pin on qiskit<1 is your own package, you might want to have your CI suite first temporarily patch your requirements file to allow Qiskit 1.0, and then install the environment in a single step as before. Alternatively, use the following rules for general-purpose environment upgrades, but switch to single-environment resolution as soon as feasible.

If at least one of your transitive dependencies does not yet have a release version that allows Qiskit 1.0 support, you must make manual changes. There are several strategies to try, in approximate order of preference (most preferable to least):

• Install the problematic dependency from its own main branch, if its development version has relaxed the pin, so you can build the test environment in a single step.
• Exclude the use of that dependency from the test environment, if possible.
• Create a test environment in the same way you would normally, and then manually override it to use Qiskit 1.0.

Manually upgrade an existing environment

To upgrade an environment in situ, follow these steps:

1. Create an environment as usual, ensuring that there are no packages that extend the qiskit or qiskit.providers namespace installed.

2. Uninstall both qiskit and qiskit-terra to make sure that neither is present:

pip uninstall --yes qiskit qiskit-terra

At this point, the environment's site-packages should not contain a qiskit directory. You don't need to verify this on every CI run, but if you are debugging a script locally, follow these steps to verify:

1. Run the following command from within the python of the virtual environment:

import site
print(site.getsitepackages())

2. Verify that those directories do not contain a qiskit directory. If they do, you likely have namespace-extending packages installed, and you should find these and remove the dependency.

3. Install the target version of Qiskit 1.0 with one of these commands:

• After the desired release candidate has been published:
  pip install 'qiskit==1.0.0rc1'

• For a main-branch dependency (or substitute whatever git revision identifier you prefer after the @).
  pip install 'git+https://github.com/Qiskit/qiskit.git@main'

You now have an environment that Qiskit allows you to test in. If import qiskit results in an ImportError, or if you are struggling to find your dependencies, see the advice in the section about the invalid-environment protections in Qiskit.

Sample manual GitHub Actions workflows

The following workflows set up a scheduled job to run overnight. This job sets up a testing environment for Qiskit 1.0 and runs pytest (or whatever test steps you need).

For a package that has no transitive dependencies qiskit<1:

on:
  schedule:
    - cron: '0 3 * * *'
jobs:
  test_main:
    name: Test Qiskit main
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Create environment
        run: |
          set -e
          # First ensure the standard tools are up-to-date.
          python -m pip install --upgrade pip wheel setuptools
          # Note that this resolves everything in a single command.
          # If it fails, at least one package likely requires `qiskit<1`.
          python -m pip install --upgrade \
            -c constraints.txt \
            -r requirements-dev.txt \
            . \
            'git+https://github.com/Qiskit/qiskit.git@main'
      - name: Run tests
        run: pytest

For a package that has unavoidable transitive dependencies that pin qiskit<1, build an invalid environment:

on:
  schedule:
    - cron: '0 3 * * *'
jobs:
  test_main:
    name: Test Qiskit main
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.10'
      - name: Create environment
        run: |
          set -e
          python -m pip install --upgrade pip wheel setuptools
          # Install the regular test environment.
          python -m pip install --upgrade \
            -c constraints.txt \
            -r requirements-dev.txt \
            .
          # Uninstall `qiskit` and `qiskit-terra`.
          python -m pip uninstall --yes qiskit qiskit-terra
          # Install the new version of Qiskit
          python -m pip install 'git+https://github.com/Qiskit/qiskit.git@main'
      - name: Run tests
        run: pytest

Sample tox configuration

The following are examples of tox.ini sections to build a testing environment for Qiskit 1.0 and run pytest (or whatever test steps you need).

If nothing prevents Qiskit 1.0 from being installed in a valid environment:

[tox]
minversion = 4.0.0
 
# This environment section should set up your regular test build.
# We'll extend it after, and this one is just an example.
[testenv]
install_command = pip install -c {toxinidir}/constraints.txt -U {opts} {packages}
deps =
    -r{toxinidir}/requirements-dev.txt
commands =
    pytest
 
# This is an override environment to install Qiskit main.
# We're assuming that you have a requirement like `qiskit>=0.45`
# in your packages metadata requirements.
[testenv:qiskit-main]
# Inherit the base dependencies, and add the additional requirement.
deps =
  [{testenv}deps]
  git+https://github.com/Qiskit/qiskit@main
# All other options, like the `commands` section, are inherited from `testenv`.

If your package or a transitive dependency has an unavoidable pin on qiskit<1, we recommend doing this testing using the manual environment construction as in the above section, because tox introduces several complexities by being more strict about environment isolation and installation order. This is correct behavior by tox (we shouldn't construct an invalid environment), but because we already know we're building an invalid environment, these checks get in the way.

[tox]
minversion = 4.0.0
 
# This environment section should set up your regular test build.
# We'll extend it later.  This is just an example.
[testenv]
install_command = pip install -c {toxinidir}/constraints.txt -U {opts} {packages}
deps =
    -r{toxinidir}/requirements-dev.txt
commands =
    pytest
 
[testenv:qiskit-main]
# Set a sequence of commands to run in the environment after everything has been installed,
# but before the main test suite.
commands_pre =
  pip uninstall --yes qiskit qiskit-terra
  pip install 'git+https://github.com/Qiskit/qiskit@main'
# All other sections, like the dependencies and the 'commands' section are inherited.

Why these changes happened

This section contains detailed information about pre-1.0 Qiskit packaging and why we made the breaking packaging change.

We know that the change is inconvenient, but this restores Qiskit to the simple package structure that most Python packages use, which will be easier for users, developers, and library authors after the Qiskit 1.0 transition is complete.

The old Qiskit structure

Historically, Qiskit was comprised of many Python distributions: qiskit-terra, the compiler core; qiskit-aer, the high-performance simulator; the original IBM Quantum™ provider; and several now-obsolete packages providing particular exploratory algorithmic or experiment-running features. For user ease, we also provided a Python distribution called qiskit, which contained no code of its own, but caused all the other components to be installed. We called this the metapackage, by analogy to similar concepts in other package managers. The code of the core of Qiskit lived in qiskit-terra, which owned the root of the Python package qiskit. In other words, qiskit-terra controlled what happened when you ran import qiskit. Until Qiskit 1.0, the qiskit package was a namespace package and contained a second namespace package at qiskit.providers.

This organization caused us and our users quite a few problems.

For example, downstream libraries that depended on Qiskit often only actually needed the compiler core, and did not require the rest of the large ecosystem that came with pip install qiskit. They would therefore correctly specify their requirement as qiskit-terra. However, when people tried to uninstall Qiskit by running pip uninstall qiskit, pip encountered problems:

• pip does not remove distributions that are now unused. So pip uninstall qiskit did almost nothing; there was no code in the distribution, so no code was removed.
• Even if it were to remove code, many downstream distributions would remain installed because they depended on qiskit-terra.
• Even if qiskit-terra was uninstalled, it might still leave an importable qiskit directory with no usable code, because it was a namespace package.

When installing or upgrading distributions with a pip install command, pip also does not take into account previous requirement resolutions. Because there were two packages, upgrading a package that required qiskit-terra to be upgraded caused an invalid environment; pip upgraded qiskit-terra but left qiskit untouched. It issued a warning on this and all subsequent pip install commands, but because nothing appeared broken, users typically ignored the warning, and pip did not raise an error status or forbid operations.

Over time, we removed elements from the qiskit metapackage until, starting with Qiskit 0.44, only qiskit-terra remains. Of these components, qiskit-aer still exists and is actively updated, but it is now installed as a separate distribution.

Similarly, we ever more strongly discouraged other libraries from using the namespace hooks. We removed the last Qiskit use of the hooks in non-obsolete packages with the release of Qiskit Aer 0.11 and its new qiskit_aer Python package, although until Qiskit 1.0 we also forced the namespace path qiskit.providers.aer to work. Starting with Qiskit 1.0, we have removed the ability for packages to extend any qiskit namespace. Thus, pip uninstall on the correct distribution in a valid environment now works as expected.

The new Qiskit structure

Starting with version 1.0, Qiskit comprises a single distribution, called qiskit, which installs one single package, also called qiskit, which owns all the code contained in its directory. This is the normal structure of Python code, and is the simplest and least error-prone structure.

The qiskit-terra distribution on PyPI will never be updated to version 1.0 or beyond; it is entirely superseded by qiskit. The name qiskit-terra is no longer involved in the installation. However, the qiskit-terra package is not being removed from PyPI, and we will leave its most recent version in a working state, so old scientific code and legacy packages can more easily continue to use it.

Unfortunately, because of the metapackage legacy and deficiencies in pip as a package manager, it is not possible for us to make a completely smooth upgrade path for users to Qiskit 1.0, especially while some packages depend on earlier versions of Qiskit, and some require only Qiskit 1.0+. These problems will lessen as more of the ecosystem migrates to Qiskit 1.0.

Troubleshooting

The packaging changes around Qiskit 1.0 are tricky, and Python's standard tool pip is not rich enough in some ways for us to communicate the changes in the distribution structures to it, which unfortunately might cause issues for users. We have tried to make Qiskit fail quickly and loudly if it detects an invalid environment, without false positives. We understand that users might find it annoying to get the error message, but in our experience, it's much better to be aware of the problem right away than for things to appear to be working on the surface, only to fail in subtle ways in the future.

This section contains packaging errors that you might see, and describes how to resolve them.

Most of these problems are not unique to Qiskit, so the advice is likely relevant, even if the problematic parts are not related to Qiskit.

import qiskit says "ModuleNotFoundError: No module named 'qiskit'"

Python cannot find your Qiskit installation.

If you definitely installed Qiskit, then you probably do not have the correct virtual environment activated. See the section on activating a virtual environment for instructions.

If you are using Jupyter and see this, ensure that Jupyter is installed into the same virtual environment as Qiskit. Exit Jupyter, activate the Qiskit virtual environment on the command line, run pip install jupyterlab (or whichever notebook interface you use), then reopen Jupyter.

import qiskit succeeds, but trying to do anything returns "AttributeError: module 'qiskit' has no attribute '...'"

This likely means that your environment had an old version of Qiskit in it alongside a package that extended its namespace (such as old versions of Qiskit Aer, or the long-obsolete Qiskit IBM Q® Provider), and then Qiskit was uninstalled. The easiest thing to do is to start a new virtual environment, and only install recent, non-obsolete packages into it.

If you have just started a new virtual environment, or you're sure that legacy packages are not the problem, make sure that your current working directory (the directory your shell session was in when you launched Python / Jupyter) does not contain a folder called qiskit. Python's default rules search the current working directory very early in the search path when trying to import a module, so a directory with a duplicate name can cause import problems.

pip refuses to install some packages together

After running a pip install command with many items on it, you might see an error such as:

ERROR: Cannot install qiskit-dynamics==0.4.4 and qiskit==1.0.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested qiskit==1.0.0
    qiskit-dynamics 0.4.4 depends on qiskit<1.0

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

This describes a true resolution conflict; there is no valid way to install all of these distributions at the same time.

In the context of Qiskit 1.0, this is likely because one of the distributions you are trying to install contains a requirement like qiskit<1.0. This means that the developers of that distribution have marked it as not (yet) compatible with Qiskit 1.0.

You can (politely) ask those developers when they will release a new version of their package that is compatible with Qiskit 1.0, but first check that they have no open issue or pull request already asking for this wherever they accept comments. Be mindful that this takes time; please give the developers a month or so to prepare new versions of their distributions! Until then, you cannot install that distribution alongside Qiskit 1.0. To continue using that distribution, create a new virtual environment and use Qiskit 0.45 or 0.46 (or whichever version it supports) alongside that other package.

You can also read the documentation from the Python packaging authority about conflict resolution(opens in a new tab).

pip succeeds but prints errors after running pip install commands

You might see an error in the output of pip, such as the following:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behavior is the source of the following dependency conflicts.
some-distribution 0.4.4 requires qiskit>=0.44,<1, but you have qiskit 1.0.0 which is incompatible.

The top line usually appears verbatim (as of pip 23.3), but second line changes depending on the exact problem, and there may be several lines like it. pip is likely to then indicate that it did whatever you wanted successfully, despite the error message.

This means that the environment is in conflict and you cannot be sure that it will work correctly. To solve the problem, examine the list of messages from pip and determine if you need all of the packages that have conflicting requirements. Sometimes there will be true conflicts between dependencies; you might need multiple virtual environments to separate out dependencies that have incompatible requirements.

The safest choice is to begin a new virtual environment (or more than one, if there are true conflicts), then delete the one in conflict.

When setting up virtual environments, run only one pip install command that includes all the dependencies you need. This is the most reliable way for pip to find a properly resolved environment with no conflicts. If you keep having problems with conflicts after setting up environments, avoid running any further pip install or pip uninstall commands; pip does not guarantee to keep the environment coherent on subsequent commands.

import qiskit raises ImportError

When running import qiskit, you might see an error such as:

ImportError: Qiskit is installed in an invalid environment that has both Qiskit 1.0+ and an earlier version. You should create a new virtual environment, and ensure that you do not mix dependencies between Qiskit pre-1.0 and post-1.0. Any packages that depend on 'qiskit-terra' are not compatible with Qiskit 1.0 and will need to be updated. Qiskit unfortunately cannot enforce this requirement during environment resolution.

The error means that Qiskit is installed in an invalid environment that includes both Qiskit 1.0 and an earlier version. This is characterized by the qiskit-terra distribution being installed alongside Qiskit 1.0. You can check what distributions are installed by running pip list, but you cannot fix this by simply uninstalling qiskit-terra.

Unfortunately, qiskit>=1.0 and qiskit-terra are conflicting distributions, and cannot both be installed together. Even more unfortunately, we cannot communicate this conflict to pip because of limitations in its metadata system.

This error most frequently arises in one of two situations:

• You ran something like pip install 'qiskit>=1' something-else, and something-else has a requirement on qiskit-terra.
• You tried to run pip install -U qiskit in an existing environment.

In both of these cases, there is no guarantee that pip will return a helpful message to you.

pip install -c https://qisk.it/1-0-constraints qiskit [other packages]

Create a working environment for Qiskit 1.0

No matter how this happened, it is much easier to make a new virtual environment.

First, we need to find out which packages are introducing a dependency on qiskit-terra. Using the broken environment, install pipdeptree from PyPI. This is a tool for generating dependency graphs:

pip install pipdeptree

Ask it which packages are introducing dependencies on qiskit-terra and qiskit (these are two separate commands):

pipdeptree --reverse --package qiskit-terra

pipdeptree --reverse --package qiskit

The outputs might look something like:

qiskit-terra==0.45.2
└── qiskit-dynamics==0.4.2 [requires: qiskit-terra>=0.23.0]

qiskit==1.0.0
├── qiskit-aer==0.13.2 [requires: qiskit>=0.45.0]
└── qiskit-ibm-provider==0.8.0 [requires: qiskit>=0.45.0]

In the above example, we have two distributions that have declared themselves compatible with Qiskit 1.0 (qiskit-aer and qiskit-ibm-provider), and one that still has a dependency on qiskit-terra.

Seeing a dependency on qiskit-terra can mean one of a few things:

• The dependent is an old package, and will not be updated to support Qiskit 1.0.

  In this case, there is no chance of using the package with Qiskit 1.0, and you will need to continue using a previous version of Qiskit. Typically this is characterized by the dependent being at its latest version (assuming the environment is new, and you didn't pin it lower) and having a direct requirement on qiskit-terra.

• The dependent is a package that is actively maintained, but does not yet support Qiskit 1.0.

  In this case, you will need to wait for the developers to release a compatible version - please be patient! Typically this is characterized by the installed distribution not being at its latest version, even though your installation command did not specify a version. You can check the latest release version of the distribution by finding its page on https://pypi.org/(opens in a new tab).

  pip likely searched old versions of the package until it found one (possibly from months or years ago) that depended only on qiskit-terra.

  This is what has happened in the example above. At the time this document was created, qiskit-dynamics==0.4.4 was the latest release version.

If you constructed this environment out of several pip install commands (such as if the environment is old and has been updated), first try to install all of your packages by using a single pip install command when you build a new environment. If the problem persists, at least one of the packages you want likely does not support Qiskit 1.0 yet, and pip is finding an old version that it believes will work because it doesn't know about the qiskit>=1/qiskit-terra conflict.

Instead, use the pipdeptree commands to identify which dependencies do not yet support Qiskit 1.0. Exclude any packages that do not yet support Qiskit 1.0 when constructing a Qiskit 1.0 environment, or continue to use a prior version of Qiskit. See Create the new environment for instructions.

Create a working environment for Qiskit 0.45 or 0.46

If you have a broken environment after trying to install Qiskit 0.45 or 0.46, the most likely situation is that pip installed Qiskit 1.0 because it tried to pick the latest versions of packages, even though it was not required. The easiest way to fix this is to create a new virtual environment, then run a single pip install command that has all the packages you need, plus an explicit 'qiskit<1' entry. If pip successfully resolves this dependency graph, you should have a working virtual environment. If at least one distribution requires Qiskit 1.0 or greater, pip should give you an error message explaining this, which looks like the one in the section on failed resolutions.

You can also use the pipdeptree commands listed in Create a working environment for Qiskit 1.0 from within the broken environment to determine which distributions have an explicit requirement on qiskit>=1.

I'm a developer, my environments are definitely right, and I'm still getting the error

First: you must be absolutely certain that your environments are correct. The test that Qiskit uses to determine a broken environment is quite robust; specifically, it queries importlib.metadata for distribution information on installed packages and checks the version numbers returned. The Qiskit 1.0 side of the test also checks for sentinel files that were present in old Qiskit versions and not Qiskit 1.0.

If you are a Qiskit developer, it's possible that you have old qiskit.egg-info or qiskit-terra.egg-info (or *.dist-info) directories present on your meta path (see sys.meta_path), left over from old editable installations. In particular, check your working directory for any *.egg-info and *.dist-info directories. If they're in the root of one of your checked out repositories, you can delete them. The worst that can happen is you might need to pip install -e . again, and even that is unlikely, because these are typically just part of the setuptools build process that doesn't get cleaned up.

If the above information does not help you and you are 100% sure that your environment is sound (or you are deliberately trying to test a broken environment):

1. Create an issue in Qiskit(opens in a new tab) explaining how this happened and why you are sure the environment is correct so we can fix it.
2. You can suppress the exception by setting the environment variable QISKIT_SUPPRESS_1_0_IMPORT_ERROR=1.