How to Install Qiskit, Cirq, and PennyLane: A Cross-Platform Setup Guide

Overview

If you are learning quantum computing for developers, the most reliable setup pattern is simple: use a fresh Python environment, install one SDK at a time first, verify with a minimal import test, and only then add notebooks, visualisation tools, or cloud connectors.

This matters because most installation problems are not really quantum problems. They are environment management problems. A broken PATH, a system Python conflict, an outdated package installer, or mixing global and local installs will derail a quantum programming tutorial faster than any circuit syntax issue.

For most readers, the safest baseline looks like this:

• Use Python 3 in a dedicated virtual environment.
• Upgrade pip, setuptools, and wheel inside that environment.
• Install only one core SDK first: Qiskit, Cirq, or PennyLane.
• Run a short verification script from the same environment you used for installation.
• Add Jupyter support only after the base import works.
• Keep a plain text record of package versions for reproducibility.

If you are still deciding which SDK to start with, see Qiskit vs Cirq vs PennyLane: Which Quantum SDK Should You Learn First?. If your main concern is where code will run after installation, our guide to Best Quantum Simulators for Developers: Features, Limits, and Free Tiers Compared is a useful companion.

Before you begin, decide which of these three usage patterns fits your goal:

• Learning locally: best for tutorials, short experiments, and repeated practice.
• Team development: best when multiple developers need a reproducible setup.
• Cloud notebook use: best when you want zero local setup or temporary experimentation.

The rest of this article is organised as a setup checklist you can return to whenever package requirements, operating systems, or workflows change.

Checklist by scenario

Use the scenario that matches your working style rather than trying to apply every step at once.

Scenario 1: Clean local setup on Windows

This is the most common starting point for developers using a laptop or workstation.

1. Confirm Python is installed correctly. Open PowerShell or Command Prompt and check your Python and pip versions. If multiple Python versions appear on your machine, note which executable is actually being used.
2. Create a dedicated project folder. Keep quantum projects separate from general Python work. This reduces package collisions and makes cleanup easier.
3. Create a virtual environment. Use the Python interpreter you intend to keep using for that project. Avoid installing these SDKs globally unless you have a strong reason.
4. Activate the environment. Make sure the shell prompt changes or otherwise confirms activation.
5. Upgrade packaging tools. Inside the environment, upgrade pip-related tooling before installing any quantum SDK.
6. Install one SDK only. Start with either Qiskit, Cirq, or PennyLane. Do not install all three together on the first attempt.
7. Run a basic import test. For example, test that the package imports without error and that a simple object such as a circuit or device can be created.
8. Install notebook support if needed. If you plan to use Jupyter, add it after the import test passes.
9. Freeze versions. Export installed packages to a requirements file so you can reproduce the same environment later.

Windows tip: if commands succeed in one terminal and fail in another, you are probably switching between environments or interpreters without realising it.

Scenario 2: Clean local setup on macOS

macOS users often have fewer PATH issues than Windows users, but there can still be confusion between system Python, package manager Python, and user-installed Python.

1. Identify the active Python binary. Check exactly which interpreter is being used before creating an environment.
2. Create a virtual environment per project. This remains the cleanest approach whether you are using Terminal or an IDE.
3. Upgrade pip tooling in the environment. Do this first, not after errors appear.
4. Install your chosen SDK. Begin with one of the following tracks: install Qiskit for IBM-oriented tutorials, install Cirq for circuit work associated with Google-style abstractions, or install PennyLane if your focus includes differentiable programming or quantum machine learning experiments.
5. Verify in both terminal and notebook contexts. A package may import in terminal Python but fail in Jupyter if the notebook kernel points elsewhere.
6. Document the setup. Save the Python version, the installed SDK version, and whether you used terminal-only or notebook-based workflows.

macOS tip: if a notebook cannot find a package you just installed, the kernel is often attached to a different environment than the shell where you ran pip.

Scenario 3: Clean local setup on Linux

Linux is usually friendly to Python-based quantum development, especially for developers already comfortable with command-line workflows.

1. Check Python and pip availability. Some distributions separate packages in ways that can be confusing at first.
2. Avoid relying on system-wide installs. Use a virtual environment rather than mixing project packages with operating system dependencies.
3. Upgrade pip tooling inside the environment.
4. Install one SDK and test immediately. Qiskit, Cirq, and PennyLane all support a local tutorial workflow, but keep the first environment minimal.
5. Add optional extras only when needed. Visualisation libraries, notebook stacks, and cloud service helpers are best treated as phase two.
6. Store requirements in version control. For team workflows, a checked-in requirements file or environment file saves time and avoids repeated machine-specific drift.

Linux tip: if you manage multiple projects, name environments clearly. A vague name like test becomes unhelpful very quickly.

Scenario 4: Cloud notebook setup

Cloud notebooks are useful when you want to avoid local installation altogether, trial a tutorial quickly, or share a reproducible learning environment with colleagues.

1. Start from a plain Python notebook. Do not assume the quantum SDK you want is already available.
2. Install packages in the first notebook cell. Keep installation commands visible in the notebook so the environment can be recreated.
3. Restart the runtime if prompted. Many notebook errors come from skipping this step after installation.
4. Run a minimal import and execution test. Create a tiny circuit, device, or simulator call before doing real work.
5. Save the notebook with environment notes. Include package versions in a markdown cell so future users understand what was tested.

Cloud notebook tip: these environments are convenient but temporary. If a tutorial matters to your team, move the working setup into a versioned local or shared environment.

Scenario 5: Team setup for workshops or internal training

If you are preparing a quantum computing tutorial for a team, setup consistency matters more than personal preference.

1. Pick one SDK per session. Mixing Qiskit, Cirq, and PennyLane in a beginner workshop usually creates avoidable confusion.
2. Standardise on one Python version. Write it down in the workshop README.
3. Provide a one-command environment bootstrap if possible. Even a small shell script or setup note reduces friction.
4. Include a verification script. Ask learners to run a short test before the session starts.
5. Prepare a fallback notebook. If local installs fail, a cloud notebook can keep the workshop moving.

This is especially useful for engineering teams exploring practical quantum computing without committing to hardware access or enterprise pilots yet.

What to double-check

These are the details most worth checking before assuming an SDK itself is broken.

1. Python version compatibility

Quantum SDKs evolve with the Python ecosystem. If installation fails, verify that your chosen Python version is supported by the package version being installed. Do not assume that the newest Python release is always the smoothest choice for every tutorial.

2. Interpreter versus installer mismatch

A classic issue is installing a package with one pip and running code with another Python interpreter. The fix is to verify that the shell, IDE, and notebook all point to the same environment.

3. Jupyter kernel alignment

If terminal imports work but notebook imports fail, the notebook kernel is usually attached to a different environment. Registering or selecting the correct kernel often resolves the issue faster than reinstalling packages repeatedly.

4. Minimal verification after install

After installing Qiskit, Cirq, or PennyLane, do not jump straight into a long tutorial. First confirm three things:

• The import works.
• A simple circuit or device object can be created.
• A basic simulation or execution call returns output.

This turns setup into a binary check: either the foundation works, or it does not.

5. Optional cloud connectors

Core local installation is different from connecting to cloud providers or managed backends. Keep those steps separate in your mind and in your documentation. If local simulators work but remote execution does not, the issue may be authentication, account configuration, or provider-specific setup rather than the SDK itself.

6. IDE configuration

VS Code, PyCharm, and other IDEs can quietly select the wrong interpreter. Always verify the selected environment before troubleshooting package errors for too long.

7. Dependency sprawl

If your environment includes many unrelated machine learning, data science, or notebook packages, isolate the quantum stack again in a fresh environment. This is especially relevant when using PennyLane alongside broader AI tooling.

Common mistakes

Most failed quantum SDK setups come down to a small set of repeatable errors.

Installing globally first

Global installs feel quicker until you need a second project with different package requirements. Virtual environments are not just best practice; they are a time-saving habit.

Installing all three SDKs at once

It is tempting to create an all-in-one quantum development environment. For exploration, that can be fine later. For first-time setup, it makes root-cause analysis harder. Install Qiskit, Cirq, or PennyLane one at a time and verify each separately.

Skipping version notes

If a setup works today and breaks after a machine refresh, package version notes become valuable immediately. Keep a requirements file, environment export, or setup README.

Assuming notebook success means environment success

A notebook may work because the platform preinstalled a package, while your local machine remains misconfigured. If the goal is reusable skill-building, verify both local and notebook workflows.

Troubleshooting the wrong layer

Some errors are package issues. Many are shell, path, kernel, or interpreter issues. Start with the environment layer before changing libraries repeatedly.

Using outdated tutorial snippets without adaptation

A good quantum computing tutorial teaches concepts, but installation commands and import paths can age faster than the conceptual material. Treat older snippets as patterns to verify, not fixed truth.

For teams evaluating tooling rather than just installation, it also helps to understand the broader vendor and platform landscape. Related reading includes The Quantum Vendor Map: Who Builds, Who Clouds, and Who Secures and How to Read Quantum Company Claims Without Getting Misled.

When to revisit

This setup guide is most useful when treated as a recurring checklist rather than a one-off read. Revisit it in the following situations:

• Before a new learning sprint: especially if you are starting a fresh Qiskit tutorial, Cirq tutorial, or PennyLane tutorial after several months away.
• Before team workshops: verify environment instructions before sending them to attendees.
• After upgrading Python: this is one of the most common triggers for installation drift.
• When moving from local simulation to cloud execution: provider setup adds a separate layer of complexity.
• When adding ML libraries: PennyLane-heavy workflows can interact with broader scientific Python stacks in ways that deserve a clean review.
• At planning cycles: if your team does seasonal tooling reviews, include quantum SDK setup and simulator access in that process.

Here is a practical maintenance routine you can adopt:

1. Create one baseline environment per SDK you actively use.
2. Store the install steps in a project README.
3. Keep a tiny verification script for each environment.
4. Retest after Python upgrades, IDE changes, or notebook platform changes.
5. Archive environments that are no longer needed instead of patching them indefinitely.

If your team is moving from tutorials toward broader quantum planning, you may also find value in From Quantum Hype to Pilot Design: A 5-Stage Framework for Choosing Enterprise Use Cases and Quantum Market Intelligence for Technical Teams: Building a Weekly Signal Tracker.

The key takeaway is simple: a good quantum development environment is not the one with the most packages installed. It is the one you can understand, reproduce, and fix quickly. Start small, verify early, document what works, and revisit the setup whenever your tools or workflows change.