quantum-exercises
Sponsor GitHub

20 hands-on Qiskit exercises

From an empty laptop to a real QPU.

One command tells you what’s wrong, in quantum terms.

You edit a file, you run one command, and it tells you exactly what is wrong in the language of the problem rather than as a Python traceback. The course ends at the Bell inequality that no shared coin can reach.

uv tool install quantum-exercises
View on GitHub See the twenty exercises

Python 3.10 to 3.14 · No IBM account needed · Free, MIT License

exercise.py

from qiskit import QuantumCircuit

# TODO: add two gates so that qc prepares (|00> + |11>) / sqrt(2).
#       Put one qubit into superposition, then tie the second to it with a
#       controlled gate. On a definite value that gate copies. On a superposition
#       there is no value to copy, and it entangles instead.
#       Do not add measurements; the runner adds them itself.
qc = QuantumCircuit(2)


# TODO: which counts bitstring means "qubit 0 was measured as 1, qubit 1 as 0"?
#       Remember which end of the string qubit 0 lives at.
label_q0_only = None


# TODO: which outcomes can an ideal Bell state never produce?
#       Give a set of strings, for example {"00", "11"}.
impossible_outcomes = None

exercise.py

from qiskit import QuantumCircuit

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

# Little-endian: qubit 0 is the rightmost character.
label_q0_only = "01"

# The two qubits always agree, so the disagreeing outcomes never occur.
impossible_outcomes = {"01", "10"}
What qx 1.0.0 prints for exercise 11, before and after the fix. The checker samples with a fixed seed, so a correct answer gets these same counts.

Nearly every quantum tutorial was written for Qiskit 0.x, and none of it runs any more. Beginners hit an ImportError on line 3 and conclude they are not smart enough. They were reading instructions for software that no longer exists.

Get the highlights.

Twenty exercises.

In four acts, from a first circuit to the Bell inequality, each ending on something your own code produced.

Errors in quantum terms.

No traceback into library code: the runner knows which concept you tripped over, so it explains the concept.

Accounts needed.

Every exercise runs on a local simulator. Real IBM hardware is optional.

Tests.

On Python 3.10 to 3.14, with every reference solution re-run and every notebook cell executed.

Checked twice a month.

On the 1st and the 15th, against the Qiskit that ships that day.

The exercises

Twenty exercises, in four acts.

You need basic Python and no quantum background. Act I takes well under an hour; the whole course is an afternoon or two, depending on how much you stop to poke at things.

Act I

Reaching a first result

  1. 01

    Your environment works

    Prove the toolchain is real, and learn the one attribute worth printing when a tutorial misbehaves.

  2. 02

    Counts is just a dictionary

    Measurement results are a plain dict. Write the three helpers you will reuse all course.

  3. 03

    Your first circuit

    Build a one-qubit circuit and see the matrix it represents.

  4. 04

    Measurement, or the result is empty

    Forget the measurement and Qiskit hands you nothing, without raising an error. Meet that trap on purpose.

  5. 05

    Reading counts out of a V2 result

    A V2 result has no get_counts(). Learn the three-step path that replaces it.

Act II

Understanding what you see

  1. 06

    The Born rule, on paper first

    Predict the probabilities before running anything, checked against 4096 real shots.

  2. 07

    States, amplitudes, and global phase

    Prepare two target states, and find out why the runner compares with equiv rather than ==.

  3. 08

    Gates are matrices

    Build a controlled-Z out of nothing but Hadamards and a CNOT.

  4. 09

    Interference: amplitudes that cancel

    Two Hadamards undo each other, which no coin can do. This is where the power comes from.

  5. 10

    Deutsch’s algorithm in one query

    Turn that cancellation into the first algorithm that provably beats every classical one.

  6. 11

    Bell state, and which bit is which

    The state that started the argument, plus which character of the bitstring is qubit 0.

Act III

The real world

  1. 12

    Why the simulator runs out

    Every qubit doubles the memory. Find the size where a laptop stops being able to check your answer.

  2. 13

    Code from 2021 that no longer runs

    Migrate real 0.x code to 2.x. This is the skill that unblocks every old tutorial you will ever find.

  3. 14

    A Bell state on a real machine

    Transpile to the backend’s instruction set and run, on a QPU if you have one.

  4. 15

    Reading a noisy result honestly

    Hardware gives outcomes the theory forbids. Quantify that instead of assuming your circuit is broken.

  5. 16

    Correcting what readout got wrong

    Measure how the device misreads, invert it, and win back most of the gap. Error mitigation, by hand.

Act IV

Expectation values, and the Bell inequality

  1. 17

    The Estimator, and what it returns

    Expectation values instead of shots, computed two ways and shown to agree.

  2. 18

    A device that only measures Z

    Hardware reads one axis. Measuring any other means rotating the state first.

  3. 19

    The picture behind the numbers

    Three expectation values put the qubit on a sphere, where global phase visibly stops mattering.

  4. 20

    CHSH, the inequality that settles it

    Correlate along different axes and reach S = 2.83, past the 2 that any pre-agreed answer is stuck below.

How answers are checked

It inspects what your code makes.

Not by comparing your code to the solution. An answer that is right for reasons the author did not anticipate still passes, and an answer that only looks right does not.

  • States

    Compared with Statevector.equiv, which ignores global phase, because no experiment can detect it.

  • Gates

    Compared with Operator.equiv, for the same reason.

  • Counts

    Never for exact equality: sampling is random. Proportions are held to the binomial standard error, sqrt(p(1-p)/N), at 4 sigma, and whole distributions to a chi-square test.

  • Its own process

    Your file runs in a separate process with a time limit, so an infinite loop or a crash costs one run, not your terminal session.

Real hardware

A real QPU, when you want one.

Exercise 14 is the only one that reaches out to IBM, and it asks before it sends anything. Answering no changes nothing and costs nothing.

  1. A real QPU, if you have an account and one is reachable.
  2. A local simulator with a noise model copied from real hardware, so the lesson about noise still lands.
  3. A plain noiseless simulator.

Say yes and qx waits up to three hours, what a real queue can take. Ctrl-C stops the waiting, not the job: its result stays in your IBM Quantum account. Nothing automated, not CI, a script or watch mode, ever reaches a QPU.

Exercise 14 run on ibm_marrakesh, a real IBM QPU. The queue question is answered yes, then the histogram shows 1024 shots: 00 at 49.0 percent, 11 at 48.4 percent, and 01 and 10 together at 2.54 percent. The summary reports the circuit as submitted, its ISA form, and that the disagreeing shots are noise rather than a bug.
Exercise 14 on ibm_marrakesh: 1,024 shots, 49.0% 00 and 48.4% 11. The 2.54% that disagree are noise, and exercise 15 is about measuring it honestly.

Where you work

Your editor, your terminal.

The exercise on one side, the verdict on the other. Four notebooks sit beside the exercises, ungraded and meant to be poked at, and every cell of every one runs in CI.

VS Code with exercise.py open on the left and the integrated terminal on the right, showing a passing run of exercise 11.
A course made by qx init needs no editor setup: qx is on your PATH, so any terminal in the folder runs it.
Watch mode running in the VS Code terminal, showing a failed check followed by the line: watching exercises/11_bell_entanglement/exercise.py, save to re-run, Ctrl-C to stop.
qx watch re-runs on every save, and moves on to the next exercise by itself when one passes.
The noise lab open in VS Code, showing an executed cell that runs the same Bell pair on three different pairs of physical qubits, and a table where the measured fidelity, 0.94, 0.88 and 0.97, tracks what the published readout rates predict.
The labs are where you are shown rather than checked, at a length an exercise cannot afford.
qx doctor --online listing ten checks, all reading ok: Python, uv, the Qiskit SDK, the Aer simulator, the IBM Runtime client, a circuit smoke test, the visualization extra, twenty exercises, the saved IBM Quantum account, and a live connection reporting three QPUs on the open plan.
Every check names the problem and the fix. Only --online asks IBM anything; plain qx doctor never touches the network.
The notebooks, opened with uv run --with quantum-exercises --with jupyterlab jupyter lab
NotebookWhat it is for
playground.ipynbScratch space. Change numbers, see what moves.
lab-1-qiskit-patterns.ipynbThe four steps of any program that touches real hardware: map, optimize, execute, post-process.
lab-2-noise.ipynbReadout error against gate error, measured on a real device’s published rates.
lab-3-dynamic-circuits.ipynbMeasuring partway through and branching on the result, ending in teleportation.

Install

Start in five steps.

uv is the only thing you install. It fetches the right Python itself, so you don’t need Python first.

  1. Install uv

    On macOS and Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh

    On Windows, in PowerShell:

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  2. Install the tool

    It puts qx on your PATH. The first run downloads Qiskit and its scientific stack, so give it a minute.

    uv tool install quantum-exercises

  3. Take a copy of the course

    Then cd quantum-exercises. Running it again never overwrites your answers.

    qx init

  4. Check that it worked

    It never touches the network, and names the fix for anything wrong.

    qx doctor

  5. Start

    It prints the first unfinished exercise: the lesson to read, and the file to edit.

    qx next
Every command. Leave the number off and it picks the first exercise you have not finished.
CommandWhat it does
qx init [dir]Copy the exercises somewhere you can edit them
qx init --refreshUpdate the lesson files of a course you already have
qx doctorCheck the environment, step by step
qx listEvery exercise and your progress
qx nextThe next thing to work on
qx run [n]Check an exercise
qx watch [n]Re-check automatically every time you save
qx hint [n]Reveal one more hint
qx solution [n]Show the answer, recorded as solved rather than done
qx reset [n]Restore an exercise to its starting state
qx versionVersions of the tool and the quantum stack

Tested

Verified against today’s Qiskit.

Every reference solution is re-run on the 1st and the 15th of every month, and if a new Qiskit release breaks an exercise, the verify badge turns red.

1,175 tests

On Python 3.10, 3.11, 3.12, 3.13 and 3.14, with coverage held at 100%.

Three systems

Ubuntu, macOS and Windows, on the 1st of every month.

The next Qiskit too

On the 1st and the 15th, a fresh resolution of every dependency, and a probe of the next major version.

A locked stack

Qiskit 2.5.2, qiskit-ibm-runtime 0.50.0 and qiskit-aer 0.17.2, pinned in uv.lock.

Questions.

What is quantum-exercises?

Twenty free, hands-on exercises for learning Qiskit, IBM’s quantum computing SDK. You edit a file, run one command, and it tells you what is wrong in the language of the problem rather than as a Python traceback. The course goes from an empty laptop to a circuit on real IBM hardware, and then to the Bell inequality.

Do I need to know quantum physics or linear algebra?

No. You need basic Python: variables, functions, and dictionaries. No quantum background, and no linear algebra beyond multiplying a small matrix by a vector. Where a matrix shows up, the runner prints it.

Do I need an IBM Quantum account?

No. Every exercise runs on a local simulator without one. Only exercise 14 reaches for real hardware, and it asks before it sends anything; without an account it runs on a simulator with a noise model copied from a real device.

How long does the course take?

Act I takes well under an hour. The whole course is an afternoon or two, depending on how much you stop to poke at things.

Which version of Qiskit does it teach?

Qiskit 2. It is tested against Qiskit 2.5.2, qiskit-ibm-runtime 0.50.0 and qiskit-aer 0.17.2, and verified on the 1st and the 15th of every month against the Qiskit that ships that day.

Why do so many Qiskit tutorials fail with an ImportError?

Most were written for Qiskit 0.x. execute() was removed, Aer moved to its own package, IBMQ became something else entirely, and the shape of results changed. Exercise 13 teaches the migration, so every old tutorial becomes usable again.

Can it spend my QPU time without asking?

No. Nothing automated reaches a QPU: a script, a CI job, an editor task and watch mode all stay on the local simulator. qx run 14 shows the least busy QPU and asks before sending, and answering no costs nothing.

Is it free?

Yes. quantum-exercises is free and open source under the MIT License.

Start with exercise 01.

Free and open source, under the MIT License.

uv tool install quantum-exercises
PyPI uv Why I built it