Setup, Versions, and Authentication

Reviewed Version Baseline

Checked against PyPI and official release notes on 2026-10-01:

Local core, Runtime/Aer, Algorithms, Optimization, and visualization checks used these releases. Nature, Machine Learning, and addons were checked against official documentation and release metadata; their workflows below are illustrative and were not executed in this refresh.

Create an Environment

The repository recommends Python 3.13. Qiskit 2.5 supports CPython 3.10 and newer on supported 64-bit platforms.

uv venv --python 3.13
source .venv/bin/activate

On Windows PowerShell:

uv venv --python 3.13
.venv\Scripts\Activate.ps1

Install the smallest useful set:

# Core SDK
uv pip install "qiskit==2.5.2"

# Core plus Matplotlib/LaTeX visualization dependencies
uv pip install "qiskit[visualization]==2.5.2"

# IBM QPUs and Runtime primitives
uv pip install "qiskit-ibm-runtime==0.50.0"

# High-performance and noisy simulation
uv pip install "qiskit-aer==0.17.2"

For a project, declare the same exact pins with uv add:

uv add "qiskit[visualization]==2.5.2"
uv add "qiskit-ibm-runtime==0.50.0"
uv add "qiskit-aer==0.17.2"

Do not install qiskit-terra. Since Qiskit 1.0, the qiskit distribution owns the complete qiskit package namespace. Aer and application packages remain separate distributions.

Optional Application Packages

Install these only for the corresponding workflow:

uv pip install "qiskit-algorithms==0.4.0"
uv pip install "qiskit-nature[pyscf]==0.8.0"
# Optional reverse integration: PySCF calls a Qiskit Nature solver
uv pip install "qiskit-nature-pyscf==0.4.0"
uv pip install "qiskit-machine-learning==0.9.1"
uv pip install "qiskit-optimization==0.7.0"

Resolve all selected packages together in a fresh environment. Do not force-install incompatible distributions with dependency checks disabled.

Verify the Environment

Use the bundled checker:

python scripts/check_environment.py
python scripts/check_environment.py --require-runtime --require-aer
python scripts/check_environment.py --json

Or inspect versions directly:

from importlib.metadata import version

for distribution in ("qiskit", "qiskit-ibm-runtime", "qiskit-aer"):
    try:
        print(distribution, version(distribution))
    except Exception:
        print(distribution, "not installed")

Run the local smoke test before configuring cloud access:

python scripts/run_local_primitives.py --shots 256 --seed 7

IBM Quantum Platform Setup

IBM QPU access requires:

1. An IBM Cloud account.
2. An IBM Quantum Platform instance or access to an organization's instance.
3. An IBM Cloud API key.
4. qiskit-ibm-runtime.

Use the current channel name, ibm_quantum_platform. The old ibm_quantum channel is no longer supported. ibm_cloud currently reaches the upgraded platform but is a legacy alias; use ibm_quantum_platform in new code.

Create and manage API keys through the IBM Cloud API keys page. Find instance names and Cloud Resource Names (CRNs) on the IBM Quantum Platform Instances page.

Trusted Workstation: Save an Account

Put only the named values into the process environment. Never hardcode, print, log, or commit an API key.

export IBM_QUANTUM_API_KEY="set-this-outside-source-control"
# Optional: restrict access to one instance
export IBM_QUANTUM_INSTANCE="instance-name-or-crn"

Then save the account from a trusted machine:

import os
from qiskit_ibm_runtime import QiskitRuntimeService

api_key = os.environ["IBM_QUANTUM_API_KEY"]
instance = os.environ.get("IBM_QUANTUM_INSTANCE")

QiskitRuntimeService.save_account(
    channel="ibm_quantum_platform",
    token=api_key,
    instance=instance,
    name="default-platform",
    set_as_default=True,
    overwrite=True,
)

The SDK stores saved credentials in $HOME/.qiskit/qiskit-ibm.json. Do not manually edit, print, upload, or commit this file. Restrict local file access to the current user.

Load saved credentials without putting a token in source:

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(name="default-platform")

If only one default account exists, QiskitRuntimeService() is sufficient. Pin the intended instance CRN for reproducible hardware work: selecting across instances can change the active billing allocation. instance="auto" explicitly opts into automatic selection; plans_preference=["open"] can restrict automatic discovery to Open Plan. The public alias IBMQuantumComputeService is also available since Runtime 0.49.

channel="local" creates a local service without cloud credentials. Never infer cloud access from a successful local service test.

CI or Ephemeral Machine: Do Not Persist

Inject the two named secrets through the CI secret store and instantiate the service directly:

import os
from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(
    channel="ibm_quantum_platform",
    token=os.environ["IBM_QUANTUM_API_KEY"],
    instance=os.environ["IBM_QUANTUM_INSTANCE"],
)

Do not call save_account() on a shared runner. Do not dump the environment, the service account object, or exception payloads that may contain request details.

If an API key is exposed, revoke it immediately in IBM Cloud and replace it everywhere it was used.

Confirm Access Without Submitting a Job

The bundled inspector uses saved credentials, performs read-only service queries, and never submits a workload:

python scripts/inspect_runtime.py --min-qubits 5
python scripts/inspect_runtime.py --backend BACKEND_NAME --json

Equivalent minimal check:

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService()
backend = service.least_busy(
    operational=True,
    simulator=False,
    min_num_qubits=5,
)
print(backend.name, backend.num_qubits)

Do not hardcode a backend name copied from an old tutorial. Available systems and access rights change.

Local-Only Development

No account or network access is needed for:

• StatevectorSampler
• StatevectorEstimator
• Statevector, DensityMatrix, and other qiskit.quantum_info tools
• Qiskit Aer simulators
• fake backends bundled with qiskit-ibm-runtime

Use local primitives for algorithm logic, Aer for larger/noisy simulations, and fake backends for target-aware compilation tests.

Repair a Broken Pre-1.0 Environment

Typical symptoms include:

• An error saying Qiskit is installed in an invalid environment.
• Both qiskit-terra and modern qiskit distributions are present.
• Imports resolve to files left behind by an old namespace-package installation.
• A notebook kernel uses a different Python interpreter from the activated environment.

The reliable repair is a new environment:

deactivate 2>/dev/null || true
uv venv --python 3.13 .venv-qiskit
source .venv-qiskit/bin/activate
uv pip install "qiskit[visualization]==2.5.2"

Avoid trying to repair a mixed pre-1.0 environment by repeatedly uninstalling individual packages; stale namespace files can remain.

Confirm the active interpreter:

import sys
import qiskit

print(sys.executable)
print(qiskit.__version__)
print(qiskit.__file__)

Upgrade Policy

For reproducible work:

1. Pin all Qiskit distributions.
2. Record Python, Qiskit, Runtime, Aer, and application-package versions with results.
3. Read the SDK and Runtime release notes before updating.
4. Re-run local primitive tests and transpilation snapshots.
5. Revalidate Runtime option names and execution-mode restrictions.
6. Upgrade in a new lockfile branch or environment, not in the middle of a paid QPU experiment.