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/guides/install-qiskit.mdx

377 lines
19 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: Install Qiskit
description: Install the Qiskit SDK and Qiskit Runtime on various operating systems
---
<span id="qiskit-install"></span>
# Install Qiskit
<iframe width="100%" height="450" src="https://www.youtube.com/embed/dZWz4Gs_BuI?si=EbbKEtvPAk7G8DRZ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
Whether you will work locally or in a cloud environment, the first step for all users is to install Qiskit. For those wanting to run on a real system, your next step is to choose one of two channels in order to access IBM Quantum&trade; systems: IBM Quantum Platform or IBM Cloud&reg;.
<Admonition type="caution" title="Upgrade from Qiskit 0.x to Qiskit 1.0 and beyond">
(If you are installing Qiskit for the first time, skip ahead to the [Install and set up](#local) section. This notice is relevant only to users who have installed Qiskit previously.)
**For those upgrading from version 0.x to 1.0 or later**: note that because Qiskit 1.0 uses a new packaging structure, you **cannot** use `pip install -U qiskit` to upgrade from any Qiskit 0.x version to 1.0.
See the [Qiskit 1.0 migration guide](/api/migration-guides/qiskit-1.0) for details and instructions.
Future updates starting with Qiskit 1.0 will allow for in-place upgrades.
</Admonition>
<span id="local"></span>
## Install the Qiskit SDK and the Qiskit Runtime client
1. Install Python. Check the "Programming Language" section on the [Qiskit PyPI project page](https://pypi.org/project/qiskit/) to determine which Python versions are supported by the most recent release. For download instructions, see the [Python Beginners Guide.](https://wiki.python.org/moin/BeginnersGuide/Download)
We recommend that you use [Python virtual environments](https://docs.python.org/3.10/tutorial/venv.html) to separate Qiskit from other applications.
<details>
<summary>
If you're new to virtual environments, click here for more information.
</summary>
A virtual Python environment is an isolated space to work with Python for a specific purpose — so you can install whatever packages you wish, and set up libraries, dependencies, and so on, without affecting the "base" Python environment on your machine.
One important advantage of a virtual environment is that if your Python environment becomes corrupted somewhere along the way, you can easily delete the virtual environment and start over!
Choose a preferred location in which to store information about your virtual environments. Commonly they're stored in a directory named `.venv` within a user's home directory.
</details>
First, create a minimal environment with only Python installed in it.
<OperatingSystemTabs>
<TabItem value="mac" label="macOS">
```shell
python3 -m venv /path/to/virtual/environment
```
</TabItem>
<TabItem value="linux" label="Linux">
```shell
python3 -m venv /path/to/virtual/environment
```
</TabItem>
<TabItem value="win" label="Windows">
```text
python3 -m venv c:\path\to\virtual\environment
```
</TabItem>
</OperatingSystemTabs>
Next, activate your new environment.
<OperatingSystemTabs>
<TabItem value="mac" label="macOS">
```shell
source /path/to/virtual/environment/bin/activate
```
</TabItem>
<TabItem value="linux" label="Linux">
```shell
source /path/to/virtual/environment/bin/activate
```
</TabItem>
<TabItem value="win" label="Windows">
```text
c:\path\to\virtual\environment\Scripts\Activate.ps1
```
</TabItem>
</OperatingSystemTabs>
1. [Install pip](https://pip.pypa.io/en/stable/installation/). Pip is a Python package manager that you use to install Qiskit and other Python packages. Use `pip list` to see what is in your virtual environment.
1. Install the Qiskit SDK. If you plan to run jobs on quantum hardware, also install Qiskit Runtime.
```shell
pip install qiskit
```
```shell
pip install qiskit-ibm-runtime
```
If you intend to use visualization functionality or Jupyter notebooks, it is recommended to install Qiskit with the extra visualization support (`'qiskit[visualization]'`).
<Tabs>
<TabItem value="default" label="Default">
```shell
pip install qiskit[visualization]
```
</TabItem>
<TabItem value="zsh" label="zsh">
```shell
pip install 'qiskit[visualization]'
```
</TabItem>
</Tabs>
1. If you want to run a Jupyter notebook with the Qiskit packages you just installed, you will need to install Jupyter in your environment.
```shell
pip install jupyter
```
Then open your notebook as follows:
```shell
jupyter notebook path/to/notebook.ipynb
```
If you are planning to work locally and use simulators built into Qiskit, then your installation is done. If you want to run jobs on IBM Quantum systems, next [select an access channel](setup-channel) and finish your setup.
<Admonition type="note" title="Stay current with the latest versions">
Periodically check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) to see new releases. We recommend frequently updating your requirements for `qiskit` and `qiskit-ibm-runtime` by, for example, changing the versions in `requirements.txt` to the latest versions.
</Admonition>
## Troubleshooting
<details>
<summary>
"No Module 'qiskit'" error with Jupyter Notebook
</summary>
If you used ``pip install qiskit`` and set up your virtual environment in
Anaconda, then you may get the ``No Module 'qiskit'`` error when you run a tutorial
in Jupyter Notebook. If you have not installed Qiskit or set up your
virtual environment, you can follow the [installation](#qiskit-install) steps.
The error is caused when trying to import the Qiskit package in an
environment where Qiskit is not installed. If you launched Jupyter Notebook
from the Anaconda-Navigator, it is possible that Jupyter Notebook is running
in the base (root) environment, instead of in your virtual
environment. Choose a virtual environment in the Anaconda-Navigator from the
**Applications on** dropdown menu. In this menu, you can see
all of the virtual environments within Anaconda, and you can
select the environment where you have Qiskit installed to launch Jupyter
Notebook.
</details>
<details>
<summary>
Compilation errors during installation
</summary>
Qiskit depends on a number of other open-source Python packages, which
are automatically installed when doing ``pip install qiskit``. Depending on
your system's platform and Python version, it is possible that a particular
package does not provide pre-built binaries for your system. You can refer
to [Operating system support](#operating-system-support) for a list of platforms supported by Qiskit, some
of which may need an extra compiler. In cases where there are
no precompiled binaries available, ``pip`` will attempt to compile the package
from source, which in turn might require some extra dependencies that need to
be installed manually.
If the output of ``pip install qiskit`` contains similar lines to:
```
Failed building wheel for SOME_PACKAGE
...
build/temp.linux-x86_64-3.5/_openssl.c:498:30: fatal error
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
```
please check the documentation of the package that failed to install (in the
example code, ``SOME_PACKAGE``) for information on how to install the libraries
needed for compiling from source.
</details>
<span id="os-support"></span>
## Operating system support
Qiskit strives to support as many operating systems as possible, but due to limitations in available testing resources and operating system availability, not all operating systems can be supported. Operating system support for Qiskit is broken into three tiers with different levels of support for each tier. For platforms outside these, such as FreeBSD or WebAssembly (WASI), Qiskit may still be installable, but it is not tested and you will have to build Qiskit (and likely Qiskit’s dependencies) from source.
Additionally, Qiskit only supports the CPython implementation of the Python language. Running with other Python interpreters such as PyPy is not supported.
<details>
<summary>
Tier 1
</summary>
Tier 1 operating systems are fully tested as part of the development processes to ensure any proposed change will function correctly. Pre-compiled binaries are built, tested, and published to PyPI as part of the release process. Typically, as long as there is a functioning Python environment installed, Qiskit can be installed on these operating systems without needing to install further dependencies.
Tier 1 operating systems:
- Linux x86_64 (distributions compatible with the [manylinux 2014](https://www.python.org/dev/peps/pep-0599/) packaging specification).
- macOS x86_64 (10.12 or later)
- macOS ARM64 (11.0 or newer)
- Windows 64-bit (Windows 10 and later supported)
</details>
<details>
<summary>
Tier 2
</summary>
Tier 2 operating systems are not tested as part of development process. However, pre-compiled binaries are built, tested, and published to PyPI as part of the release process and these packages can be expected to be installed with just a functioning Python environment.
Tier 2 operating systems:
- Linux AArch64 (distributions compatible with the [manylinux 2014](https://www.python.org/dev/peps/pep-0599/) packaging specification)
</details>
<details>
<summary>
Tier 3
</summary>
Tier 3 operating systems are not tested as part of the development process. Pre-compiled binaries are built and published to PyPI as part of the release process but are not tested. They may not be installable with just a functioning Python environment and might require a C/C++ compiler or additional programs to build dependencies from source as part of the installation process. Support for these operating systems are best effort only.
Tier 3 operating systems:
- Linux ppc64le (distributions compatible with the [manylinux 2014](https://www.python.org/dev/peps/pep-0599/)packaging specification)
- Linux s390x (distributions compatible with the [manylinux 2014](https://www.python.org/dev/peps/pep-0599/) packaging specification)
- Linux i686 (distributions compatible with the [manylinux 2014](https://www.python.org/dev/peps/pep-0599/) packaging specification)
- Windows 10 32-bit
</details>
## Qiskit versioning
Qiskit version numbers follow [Semantic Versioning](https://semver.org/).
The version number is comprised of three primary components: the major, minor, and
patch versions. For example, in version number `X.Y.Z`, `X` is the major version,
`Y` is the minor version, and `Z` is the patch version.
Breaking API changes are reserved for major version releases. The **minimum**
period between major version releases is one year. Minor versions introduce
new features and bug fixes without breaking API compatibility, and are
periodically (currently every three months) published for **only** the
current major version. Patch versions provide fixes for bugs identified in
the most recent minor version of each actively supported release series (that is, the
major version). We support at most two release series at a time, which occurs
only during the period of overlap following a new major version release,
described in more detail below.
<details>
<summary id="release-schedule">
Release schedule
</summary>
A tentative release schedule is included below:
![Tentative Qiskit release schedule](/images/guides/install/release_schedule.png)
For an up-to-date release schedule, refer to the Qiskit Github project's [milestones list](https://github.com/Qiskit/qiskit/milestones), which will always contain the current release plan.
With the release of a new major version, the previous major version is supported
for at least six months; only bug and security fixes are accepted during this time and only patch releases are published for this major version. A final
patch version is published when support is dropped, and that release
also documents the end of support for that major version series. A longer
support window is needed for the previous major version as this gives downstream
Qiskit consumers and their users a chance to migrate their code.
Downstream libraries that
depend on Qiskit should not raise their minimum required Qiskit version to a new
major version immediately after its release because the library's user base needs time
to migrate to the new API changes. Having an extended support window
for the previous major Qiskit version gives downstream projects time to ensure
compatibility with the next major version. Downstream projects can provide
support for two release series at a time to give their users a migration path.
For the purposes of semantic versioning, the Qiskit public API is considered
any documented module, class, function, or method that is not marked as private
(with an underscore `_` prefix). However, there can be explicit exceptions made for
specific documented APIs. In such cases, these APIs will be clearly documented
as not being considered stable interfaces yet, and a user-visible warning will be
actively emitted on any use of these unstable interfaces. Additionally, in some
situations, an interface marked as private is considered part of the public
API. Typically this only occurs in two cases: either an abstract interface
definition where subclasses are intended to override/implement a private method
as part of defining an implementation of the interface, or advanced-usage
low-level methods that have stable interfaces but are not considered safe to use,
as the burden is on the user to uphold the class/safety invariants themselves
(the canonical example of this is the `QuantumCircuit._append` method).
The supported Python versions, minimum supported Rust version (for building
Qiskit from source), and any Python package dependencies (including the minimum
supported versions of dependencies) used by Qiskit are not part of the backwards
compatibility guarantees and may change during any release. Only minor or major
version releases will raise minimum requirements for using or building Qiskit
(including adding new dependencies), but patch fixes might include support for
new versions of Python or other dependencies. Usually the minimum version of a
dependency is only increased when older dependency versions go out of support or
when it is not possible to maintain compatibility with the latest release of the
dependency and the older version.
</details>
<details>
<summary id="upgrade-strategy">
Upgrade strategy
</summary>
When a new major version is released, the recommended upgrade path
is to first upgrade to the most recent minor version on the previous major
version. Shortly before a new major version, a final minor version will
be published. This final minor version release `X.Y+1.0.0` is equivalent to
`X.Y.0` but with warnings and deprecations for any API changes that are
made on the new major version series.
For example, immediately proceeding the 1.0.0 release, a 0.46.0 release will be
published. The 0.46.0 release will be equivalent to the 0.45.0 release but with
additional deprecation warnings that document the API changes that were made as
part of the 1.0.0 release. This pattern will be used for any future major
version releases.
Qiskit users should first upgrade to this final minor
version to see any deprecation warnings and adjust their Qiskit
usage before trying a potentially breaking release. The previous
major version will be supported for at least six months to give sufficient time
to upgrade. A typical pattern to manage this is to pin the maximum version to
avoid using the next major release series until you're sure of compatibility.
For example, specifying `qiskit<2` in a requirements file when the current
major Qiskit version is 1 ensures that you're using a version of Qiskit
that doesn't have breaking API changes.
Capping the version less than the next major version
ensures that you see any deprecation warnings before a
major version release.
Without the cap, `pip` installs
the newest version available by default.
The QPY serialization format is backwards-compatible so that a new Qiskit release can always load a QPY
file generated with an earlier release of Qiskit. However, the format isn't forward-compatible so, in principle, it's not possible
to load QPY files generated with a newer version of Qiskit using an older release. To facilitate user migration across major version releases, the (`qiskit.qpy.dump()`](/api/qiskit/qpy#dump) function will always support at least one overlapping version between the `X.0.0` and the `X-1.Y.0` release (where `Y` is the last minor version of
that series). The parameter `qiskit.qpy.dump(..., version=...)` will enable saving QPY format files that can be loaded by both major versions from the newer
release. See more details in [RFC 0020](https://github.com/Qiskit/RFCs/blob/master/0020-release_cycle.md#qpy-support).
</details>
<details>
<summary id="pre-releases">
Pre-releases
</summary>
For each minor and major version release, Qiskit publishes pre-releases that
are compatible with [PEP440](https://peps.python.org/pep-0440/). Typically
these are release candidates of the form `X.Y.0rc1`. The `rc` releases
will have a finalized API surface and are used to test a prospective release.
Note that when one of the PEP440 pre-release suffixes (such as `a`, `b`, or `pre`) are
published, it does not have the same guarantees as an `rc` release, and is
only a preview release. The API might change between these pre-releases
and the final release with that version number. For example, `1.0.0pre1` might have
a different final API than `1.0.0`.
</details>
<details>
<summary id="post-releases">
Post-releases
</summary>
If there are issues with a release's packaging, a post-release might be
issued to correct this. These will follow the form `X.Y.Z.1` where the fourth
integer indicates that it is the first post-release of the `X.Y.Z` release.
For example, the qiskit-terra (the legacy package name for Qiskit) 0.25.2
release had some issue with the sdist package publishing, and a post-release
0.25.2.1 was published that corrected this issue. The code was identical, and
0.25.2.1 only fixed the packaging issue for the release.
</details>
## Next steps
<Admonition type="tip" title="Recommendations">
- [Select and set up an IBM Quantum channel.](setup-channel)
- [Configure Qiskit locally.](configure-qiskit-local)
- Follow the steps in [Hello world](hello-world) to write and run a quantum program.
- Try one of the [workflow example tutorials.](https://learning.quantum.ibm.com/catalog/tutorials?category=workflow-example)
</Admonition>
Reference in New Issue View Git Blame Copy Permalink