Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improvements to install page #1721

Merged
merged 7 commits into from
Jul 17, 2024
Merged
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 24 additions & 19 deletions docs/guides/install-qiskit.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,11 @@ Whether you will work locally or in a cloud environment, the first step for all
<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.
**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.
beckykd marked this conversation as resolved.
Show resolved Hide resolved

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Future updates starting with Qiskit 1.0 will allow for in-place upgrades.
Future updates starting with Qiskit v1.0 will allow for in-place upgrades.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The newest guidance has us using a v after Qiskit and before the version number. (Unfortunately this means the name of the migration guide doesn't match)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it - thanks!

</Admonition>

<span id="local"></span>
Expand All @@ -26,7 +26,11 @@ Whether you will work locally or in a cloud environment, the first step for all

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.
It is recommended that you use [Python virtual environments](https://docs.python.org/3.10/tutorial/venv.html) to separate Qiskit from other applications.

<Admonition type = "note">
These instructions use the standard Python distribution from pypi.org. However, you can use other Python distributions, such as [Anaconda](https://docs.anaconda.com/anaconda/) or [miniconda](https://docs.anaconda.com/miniconda/), along with other dependency management workflows like [Poetry](https://python-poetry.org/docs/).
beckykd marked this conversation as resolved.
Show resolved Hide resolved
</Admonition>

<details>
<summary>
Expand All @@ -35,11 +39,11 @@ Whether you will work locally or in a cloud environment, the first step for all
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.

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.
First, create a minimal environment with only Python installed in it.

<OperatingSystemTabs>
<TabItem value="mac" label="macOS">
Expand Down Expand Up @@ -83,7 +87,7 @@ Whether you will work locally or in a cloud environment, the first step for all
</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 pip](https://pip.pypa.io/en/stable/installation/) if it's not already installed in your environment. 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. In most Python environments, pip is already installed.

1. Install the Qiskit SDK. If you plan to run jobs on quantum hardware, also install Qiskit Runtime.

Expand Down Expand Up @@ -112,6 +116,7 @@ Whether you will work locally or in a cloud environment, the first step for all
</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
Expand All @@ -126,7 +131,7 @@ Whether you will work locally or in a cloud environment, the first step for all
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.
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, then running `pip install -r requirements.txt` or the appropriate command for your dependency management workflow.
</Admonition>

## Troubleshooting
Expand Down Expand Up @@ -238,7 +243,7 @@ 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
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.
Expand All @@ -257,13 +262,13 @@ For an up-to-date release schedule, refer to the Qiskit Github project's [milest

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
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
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
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
Expand Down Expand Up @@ -322,15 +327,15 @@ 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
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
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
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>
Expand Down