A reliable Qiskit project starts with a controlled Python environment, not with the first circuit. This guide provides a reusable setup checklist for virtual environments, package installation, Jupyter, provider credentials, dependency files, and compatibility checks so you can move between computers or upgrade tools without losing a working quantum programming workflow.
Overview
Qiskit projects commonly combine several moving parts: Python, the core Qiskit SDK, optional simulators, notebook tools, and provider-specific packages for remote quantum services. These components may release on different schedules, and package names or import paths can change between major releases. Installing everything globally with an unpinned command can therefore create difficult-to-reproduce errors.
The safest default is to create one isolated environment per project. Record the Python version, install only the packages that project needs, verify imports immediately, and save the resulting dependency information. Treat the environment as part of the experiment: a circuit result is easier to reproduce when its SDK, simulator, backend settings, and execution instructions are documented together.
Before beginning, decide which workflow you need:
- Local learning: Python, Qiskit, and a local simulator are usually enough.
- Notebook development: Add Jupyter and register the project environment as a kernel.
- Remote execution: Add the provider package required by the service and configure credentials outside the source code.
- Reproducible research: Pin or constrain dependencies, record operating-system details, and preserve a small verification script.
For broader SDK comparisons, see Qiskit vs. Cirq vs. PennyLane. If you are building a study plan rather than a single project, the quantum computing roadmap can help place environment setup in context.
Checklist by scenario
1. Create a clean Python environment
Use a supported Python release for the Qiskit version you intend to install. Confirm the interpreter before creating the environment:
python --versionOn systems where python points to another interpreter, use python3 instead. Create and activate a project-specific environment:
python -m venv .venv
# macOS or Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1Upgrade the packaging tools inside the environment, then install the packages your project actually uses:
python -m pip install --upgrade pip
python -m pip install qiskit
# Add only if local simulation is required
python -m pip install qiskit-aerUsing python -m pip helps ensure that pip belongs to the active interpreter. If a course, repository, or research group provides a requirements file, install that file instead of mixing ad hoc commands with it.
2. Add Jupyter without losing the environment
For notebooks, install Jupyter and the kernel package in the same virtual environment:
python -m pip install jupyter ipykernel
python -m ipykernel install --user --name qiskit-project --display-name "Python (qiskit-project)"
jupyter labOpen a notebook and select the qiskit-project kernel. Then verify the selected interpreter from a cell:
import sys
print(sys.executable)The path should point to the project’s .venv, not to a system Python or a different Conda environment.
3. Add a remote provider deliberately
Remote execution requires a provider-specific client, an account or API key, and access to the service’s current authentication workflow. Install the provider package named in its current documentation rather than assuming that an older tutorial’s package name is still valid. For IBM Quantum workflows, this may involve the current IBM Runtime client and its documented Qiskit integration.
Keep credentials out of notebooks, Git repositories, and shared screenshots. Prefer the provider’s documented account-saving mechanism or environment variables. Test authentication with a minimal connection script before combining it with a larger circuit.
4. Save the environment
After confirming that imports and a small circuit work, record direct dependencies:
python -m pip freeze > requirements-lock.txtA fully frozen file is useful for restoring a known environment, but it can contain platform-specific or transitive packages. For a reusable project, also maintain a short human-edited requirements file or project configuration that identifies direct dependencies and acceptable version ranges. Commit both only when their purpose is clear.
Compatibility table: what to verify before installing
There is no permanent compatibility matrix because Python releases, Qiskit components, simulators, provider clients, and operating-system support change over time. Use this table as a release-checking worksheet rather than as a promise that every combination works.
| Component | Check before setup | Practical rule |
|---|---|---|
| Python | Supported versions listed by the target Qiskit release | Choose one supported version and record it in project documentation. |
| Qiskit | Core package name, release notes, and installation instructions | Do not mix commands from tutorials written for different major releases. |
| Local simulator | Whether the simulator is bundled or installed separately | Install the simulator package explicitly when your code imports it directly. |
| Provider client | Current package name, authentication method, and supported Qiskit integration | Follow the provider’s current guide and test credentials independently. |
| Jupyter | Kernel registration and interpreter selection | Install and register the kernel from the active virtual environment. |
| Operating system | Python, compiler, wheel, and shell support for your platform | Repeat the smoke test on each operating system used by the team. |
When upgrading, check package release notes and dependency metadata first. If a tutorial uses an import that fails, determine whether the API moved, the optional package is missing, or the tutorial targets an earlier release.
What to double-check
- Interpreter identity: Run
python -c "import sys; print(sys.executable)"and confirm the path is inside the intended environment. - Package visibility: Run
python -m pip show qiskitand inspect the installed location. - Core import: Test
import qiskitbefore opening a notebook or connecting to hardware. - Simulator import: If used, test the simulator package separately rather than assuming the core package includes it.
- Version record: Capture package versions with
python -m pip listor a lock file. - Provider access: Confirm the account, project or workspace selection, and backend availability using a minimal provider example.
- Reproducibility: Record circuit depth, number of shots, transpilation options, backend name, and random seeds where applicable. The quantum experiment reproducibility checklist covers the wider record.
Once the environment passes these checks, run a tiny circuit locally before attempting a larger experiment. For example, create a one-qubit circuit, apply a gate, measure it, and inspect the counts. This separates environment problems from circuit-logic problems. For a structured debugging process, use this Qiskit circuit debugging workflow.
Common mistakes
Installing globally
Global installations make unrelated projects share dependencies. A package upgrade for one notebook can silently break another. Use a separate environment and document how to activate it.
Copying old import statements
Quantum SDK tutorials often remain online after APIs change. Check the tutorial’s assumed Qiskit generation and compare its imports with current documentation before changing your environment to accommodate old code.
Installing every optional package
Adding simulators, provider clients, visualization libraries, and unrelated tools at once increases the conflict surface. Start with the smallest working set, then add one dependency at a time.
Confusing a notebook kernel with an environment
Activating a shell environment does not automatically change an already running Jupyter kernel. Select the correct kernel and verify sys.executable.
Saving secrets in source control
Never commit API keys to notebooks or configuration files. Remove exposed credentials according to the provider’s current security instructions and replace them when necessary.
Changing versions while debugging results
If a circuit produces an unexpected result, avoid upgrading several packages simultaneously. First preserve the current environment, record versions, and isolate whether the issue is installation, API behavior, transpilation, or circuit logic.
When to revisit the setup
Revisit this checklist whenever you begin a new project, move to another computer, restore an old notebook, change Python versions, add a simulator, connect to a provider, or upgrade a major Qiskit component. It is also worth reviewing before a class, paper, workshop, or team handoff so everyone uses the same documented environment.
At least once each quarter, compare your setup notes with the current Qiskit, simulator, provider, Python, and Jupyter documentation. A practical update routine is:
- Create a copy of the existing environment or branch before upgrading.
- Read release notes for every direct dependency.
- Test imports, notebook kernel selection, a local circuit, and provider authentication separately.
- Run representative project tests and compare results with a known baseline.
- Update the requirements or lock file only after the checks pass.
- Record breaking changes and the date of the verification in the project README.
Finish each setup with a small smoke-test script that prints the Python version, package versions, and a deterministic local circuit result where appropriate. That short test becomes your first diagnostic tool when an import fails or a notebook behaves differently on another machine.