scnc
/
qiskit-documentation
mirror of https://github.com/Qiskit/documentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
qiskit-documentation/docs/migration-guides/qiskit-1.0-installation.mdx

688 lines
39 KiB
Plaintext
Raw Permalink Blame History

---
title: Qiskit 1.0 installation and packaging changes
description: Adapt to changes in installing and depending on Qiskit 1.0
---
{/* cspell:ignore jupyterlab */}
# 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.
<Admonition type="caution">
Do not try to upgrade an existing Python virtual environment to Qiskit 1.0 in-place.
</Admonition>
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](#for-users) section.
* If you develop or maintain a package that depends on Qiskit, read the [For developers](#for-developers) section.
* If you are interested, review the [What is changing and why it changed](#why-did-this-happen) section.
* If you encounter problems installing or importing Qiskit 1.0, review the [Troubleshooting](#troubleshooting) section.
<span id="for-users"></span>
## 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.
<Admonition type="note">
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.
</Admonition>
<span id="creating-a-venv"></span>
### 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`.
<OperatingSystemTabs>
<TabItem value="mac" label="macOS">
```bash
python3 -m venv /path/to/qiskit-1.0-venv
```
</TabItem>
<TabItem value="linux" label="Linux">
```bash
python3 -m venv /path/to/qiskit-1.0-venv
```
</TabItem>
<TabItem value="win" label="Windows">
```powershell
python3 -m venv C:\path\to\qiskit-1.0-venv
```
</TabItem>
</OperatingSystemTabs>
<span id="activate"></span>
2. Activate the environment.
<OperatingSystemTabs>
<TabItem value="mac" label="macOS">
```bash
source /path/to/qiskit-1.0-venv/bin/activate
```
</TabItem>
<TabItem value="linux" label="Linux">
```bash
source /path/to/qiskit-1.0-venv/bin/activate
```
</TabItem>
<TabItem value="win" label="Windows">
```powershell
C:\path\to\qiskit-1.0-venv\Scripts\activate.ps1
```
</TabItem>
</OperatingSystemTabs>
3. Install packages as desired.
You should do this by using only one `pip install` command with all the dependencies on it.
```bash
pip install 'qiskit>=1'
```
You can optionally include additional packages by including them as arguments. For example:
```bash
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`.
<Admonition type="tip">
One way to require `pip` to forbid `qiskit-terra` from individual `install` commands is to use [a constraints file](https://pip.pypa.io/en/stable/user_guide/#constraints-files) 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](https://qisk.it/1-0-constraints), which you can use like this:
```bash
pip install -c https://qisk.it/1-0-constraints qiskit [other packages]
```
If a package requires `qiskit-terra`, you will see [a resolution failure](#pip-resolution-impossible).
</Admonition>
<Admonition type="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.
</Admonition>
If you have an existing environment, you can use [`pipdeptree`](https://github.com/tox-dev/pipdeptree/blob/main/README.md#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](#troubleshooting) section, or ask on [Qiskit Slack](https://qisk.it/join-slack). If you think there is a bug, you can [create an issue against Qiskit](https://github.com/Qiskit/qiskit/issues/new/choose).
4. If you are not planning to use the environment immediately, use the `deactivate` command to leave it.
<span id="activating-a-venv"></span>
### Use the new environment
Each time you start a new command line session, you must "activate" the environment by running the `activate` command:
<OperatingSystemTabs>
<TabItem value="mac" label="macOS">
```bash
source /path/to/qiskit-1.0-venv/bin/activate
```
</TabItem>
<TabItem value="linux" label="Linux">
```bash
source /path/to/qiskit-1.0-venv/bin/activate
```
</TabItem>
<TabItem value="win" label="Windows">
```powershell
C:\path\to\qiskit-1.0-venv\Scripts\activate.ps1
```
</TabItem>
</OperatingSystemTabs>
<span id="for-developers"></span>
## 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.](https://github.com/numpy/numpy/issues/24300)
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
<Admonition type="caution">
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.
</Admonition>
<Admonition type="note">
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.
</Admonition>
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:
```bash
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:
```python
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:
```bash
pip install 'qiskit==1.0.0rc1'
```
* For a `main`-branch dependency (or substitute whatever `git` revision identifier you prefer after the `@`).
```bash
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](#qiskit-1.0-import-error) 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`:
```yaml
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:
```yaml
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:
```ini
[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.
```ini
[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.
```
<span id="why-did-this-happen"></span>
## 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.
<Admonition type="info" title="Python packaging terminology">
This section uses some Python-packaging jargon to better explain what was happening.
The following words have special meanings:
* *module*: A single Python file.
* *package*: A directory containing an `__init__.py` and other files or packages that Python can read.
This is the actual code as installed on your computer, and is what executes when you run `import something`.
Python considers any directory that is on the search path to be something you can import (and will import many additional items).
This is not the same object that you `pip install` (which is a *distribution*), but typically what you `pip install` and what you `import` have the same name.
* *submodule*, *subpackage*: These are imprecise terms, but are commonly used.
The _sub_ part means "contained inside a package".
A submodule is a module and a subpackage is a package, but they are part of a larger package.
* *namespace package*: A package that can have submodules or subpackages installed into it by other _distributions_.
Critically, no one distribution contributing to a namespace package necessarily owns all the installed files, so it can be tricky to completely uninstall
or upgrade one.
* *distribution*: The compressed Python files, data files, and metadata that are downloaded when you run `pip install something`.
Often, a distribution contains exactly one package and the metadata about how to install it (its requirements and so on), but this is not required.
A distribution can contain zero or more modules or packages.
If you are familiar with "package managers" outside the context of Python, such as `apt` from Debian/Ubuntu or Homebrew on macOS, then what they call a "package", Python calls a distribution, and there is no exact match for what Python calls a package.
Most sources talking about Python packaging use the term _package_ to mean both distributions and packages, and you must refer to the context to understand what is meant.
In general, if you `import` it, the source means "package", and if you `pip install` it, the source means "distribution".
* *search path*: When trying to `import something`, Python searches a predefined list of places for a module or package called `something`.
The list of places is the _search path_.
You can see and modify the search path in `sys.path`.
* *requirement*: A distribution contains information on other distributions it depends on when installed.
Any other distribution that is necessary is a _requirement_, and the package manager (usually `pip` or `conda`) should ensure that all requirements are installed with compatible versions.
Python is highly dynamic, and many complexities can arise; for example, it's possible that a module or package does not correspond to files on disk, or that they are compiled extensions.
The search path is not only a search over directories, but for this discussion, only files on disk are relevant.
Further complications aren't necessary to understand the problems described in this section, so you can use the model described above.
</Admonition>
### 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&trade; 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.
<Admonition type="note">
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.
</Admonition>
<span id="troubleshooting"></span>
## 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](#activating-a-venv) 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&reg; 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.
<span id="pip-resolution-impossible"></span>
### `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:
```text
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.
<Admonition type="caution">
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.
</Admonition>
You can also read [the documentation from the Python packaging authority about conflict resolution](https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts).
### `pip` succeeds but prints errors after running `pip install` commands
You might see an error in the output of `pip`, such as the following:
```text
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.
<Admonition type="note">
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.
</Admonition>
<span id="qiskit-1.0-import-error"></span>
### `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.
<Admonition type="tip">
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.
</Admonition>
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.
<Admonition type="tip">
One way to require `pip` to forbid `qiskit-terra` from individual `install` commands is to use [a constraints file](https://pip.pypa.io/en/stable/user_guide/#constraints-files) 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](https://qisk.it/1-0-constraints), which you can use like this:
```bash
pip install -c https://qisk.it/1-0-constraints qiskit [other packages]
```
If a package requires `qiskit-terra`, you will see [a resolution failure](#pip-resolution-impossible).
</Admonition>
<span id="debug-venv-for-1.0"></span>
#### 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:
```bash
pip install pipdeptree
```
Ask it which packages are introducing dependencies on `qiskit-terra` and `qiskit` (these are two separate commands):
```bash
pipdeptree --reverse --package qiskit-terra
```
```bash
pipdeptree --reverse --package qiskit
```
The outputs might look something like:
```text
qiskit-terra==0.45.2
└── qiskit-dynamics==0.4.2 [requires: qiskit-terra>=0.23.0]
```
```text
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`.
<Admonition type="tip">
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.
</Admonition>
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](#creating-a-venv) for instructions.
<Admonition type="note">
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.
</Admonition>
<span id="debug-venv-for-0.45"></span>
#### 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](#pip-resolution-impossible).
You can also use the `pipdeptree` commands listed in [Create a working environment for Qiskit 1.0](#debug-venv-for-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](https://github.com/Qiskit/qiskit/issues/new/choose) 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`.
Reference in New Issue View Git Blame Copy Permalink