diff --git a/docs/guides/install-qiskit.mdx b/docs/guides/install-qiskit.mdx
index 0d02e9a5af7..bf631006abc 100644
--- a/docs/guides/install-qiskit.mdx
+++ b/docs/guides/install-qiskit.mdx
@@ -13,11 +13,11 @@ Whether you will work locally or in a cloud environment, the first step for all
(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 v1.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.
@@ -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.
+
+
+ These instructions use the standard Python distribution from [pypi.org](https://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/).
+
@@ -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.
- First, create a minimal environment with only Python installed in it.
+ First, create a minimal environment with only Python installed in it.
@@ -83,7 +87,7 @@ Whether you will work locally or in a cloud environment, the first step for all
-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.
@@ -112,6 +116,7 @@ Whether you will work locally or in a cloud environment, the first step for all
+
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
@@ -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.
- 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.
## Troubleshooting
@@ -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.
@@ -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
@@ -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).