Pas encore traduit

Cette page n'a pas encore été traduite. Vous voyez la version originale en anglais.

Install the new Qiskit 1.0 package

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

attention

Do not try to upgrade an existing Python virtual environment to Qiskit 1.0 in-place.

We will not make similar breaking packaging changes in the future. This is a one-time event, at the release of Qiskit 1.0, specifically so that our packaging story will be as easy as possible in the future.

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 encounter problems installing or importing Qiskit 1.0, review the Troubleshooting section.

If you are interested in understanding the old package structure and why it changed, review the overview of the breaking package changes.

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.

remarque

The examples in this section use the venv module that is part of the Python standard library. If you use a different tool, such as virtualenv or conda, consult its documentation for help.

For Linux and macOS commands, a bash-like syntax is used. PowerShell is used for Windows commands.

Create the new environment

1. Create a new virtual environment in each project directory you're working in, using your preferred version of Python 3.8 or later.

   macOS

   python3 -m venv .venv

   Linux

   python3 -m venv .venv

   Windows

   python -m venv .venv

2. Activate the environment.

   macOS

   source .venv/bin/activate

   Linux

   source .venv/bin/activate

   Windows

   .venv\Scripts\activate.ps1

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.

   conseil

   One way to require pip to forbid qiskit-terra from individual install commands is to use a constraints file 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, 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.

   attention

   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 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. If you think there is a bug, you can create an issue against Qiskit.

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 navigate to your project directory and "activate" the environment by running the activate command:

macOS

source .venv/bin/activate

Linux

source .venv/bin/activate

Windows

.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.

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

attention

This process deliberately creates an invalid environment. Therefore, any test using it is less valid. Tests might appear to pass, but this does not guarantee that the package is compatible with Qiskit 1.0. This could happen because the environment is not self-consistent and could contain files that do not exist in a valid environment, or the behavior of an overridden package might change with Qiskit 1.0.

remarque

If one of your dependencies pins qiskit<1 even on their development branch, it might not work in any way with Qiskit 1.0, and if your tests cannot run because of this, you might have to wait for them (or work with them) to become compatible.

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.

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.

attention

If you get this error, do not try to build the environment by calling pip install several times. Those commands will probably not fail, but you will have created an invalid environment. You would likely then see some of the other error messages described in this section.

You can also read the documentation from the Python packaging authority about conflict resolution.

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.

remarque

If you are concerned about working with multiple virtual environments, rest assured that Python development and use often involve several virtual environments. It's common and good practice to create new ones to work on separate projects. When you're done with a virtual environment, you can simply delete its directory; there is no reason to keep multiple environments permanently.

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.

conseil

You might have run a completely valid pip install command, following all the recommendations in this guide, and still see this error message. This is not your fault, but the error message is still correct, and Qiskit cannot safely load.

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.

conseil

One way to require pip to forbid qiskit-terra from individual install commands is to use a constraints file 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, 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.

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.

conseil

This example is a flat dependency structure. You might see a much deeper tree than this. The packages that are directly dependent on qiskit-terra (lowest indentation) are most likely to be the problematic ones, but one farther down the tree could be problematic if it depends on a specific old version of some other package that has already been updated.

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/.

  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.

remarque

The example in this section was generated before Qiskit 1.0 was released.

The "old" distribution in question (qiskit-dynamics) was behaving correctly; it was not known to support Qiskit 1.0 yet, so it marked that in its requirements. It's not possible to backdate requirements changes to previously released versions, and pip will search arbitrarily far back to locate something that works when building an environment.

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 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.