Qiskit Tutorial for Beginners: Build, Run, and Measure Your First Quantum Circuit
Qiskitquantum programmingquantum circuitsbeginner tutorialIBM QuantumPythondeveloper guides

Qiskit Tutorial for Beginners: Build, Run, and Measure Your First Quantum Circuit

JJustQubit Editorial Team
2026-11-01
7 min read

Build, simulate, measure, and troubleshoot your first Qiskit circuit with a reusable checklist for local and cloud execution.

This Qiskit tutorial for beginners walks through a complete first experiment: create a circuit, apply gates, measure a qubit, run it on a local Qiskit simulator, and prepare the same workflow for a cloud quantum backend. It also includes a reusable checklist for handling changing package APIs, backend requirements, and common setup errors.

Overview

Qiskit is a Python-based framework for building and executing quantum circuits. A circuit is a sequence of operations applied to qubits, followed by measurements that convert quantum outcomes into classical data. If you are new to quantum programming, the most useful first goal is not to implement a complicated algorithm. It is to understand the full development loop:

  1. Define the number of qubits and classical bits.
  2. Add gates that change the quantum state.
  3. Add measurements.
  4. Transpile the circuit for a selected execution target.
  5. Run repeated shots and inspect the resulting counts.

A qubit can be measured as either 0 or 1, but gates can place it in a state that produces both outcomes with different probabilities. The Hadamard gate, written as h in Qiskit, is a useful beginner example because it puts a qubit into an even superposition when starting from the usual |0⟩ state. Repeating the circuit many times should produce a distribution close to half 0 and half 1 on an ideal simulator. Individual results are still probabilistic.

Before starting, use a dedicated Python virtual environment. Qiskit and its execution providers can change independently, so isolating the project makes it easier to reproduce a working setup and troubleshoot package conflicts.

python -m venv .venv

# macOS or Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install qiskit qiskit-aer

Package names and APIs should always be checked against the Qiskit documentation for the version you installed. The example below uses the commonly available local Aer simulator workflow and keeps the circuit intentionally small.

Checklist by scenario

Scenario 1: Build and inspect a one-qubit circuit

Create a file named first_circuit.py:

from qiskit import QuantumCircuit

circuit = QuantumCircuit(1, 1)
circuit.h(0)
circuit.measure(0, 0)

print(circuit)

QuantumCircuit(1, 1) creates one qubit and one classical bit. Qiskit uses zero-based indexing, so qubit 0 is the first and only qubit here. The Hadamard gate is applied before measurement. Measurement stores the result from qubit 0 in classical bit 0.

Printing the circuit is a simple but valuable debugging step. Confirm that the diagram contains the expected gate and a measurement operation before sending anything to a simulator or remote device.

Scenario 2: Run the circuit on a local simulator

Extend the file with an Aer simulator:

from qiskit import QuantumCircuit, transpile
from qiskit_aer import AerSimulator

circuit = QuantumCircuit(1, 1)
circuit.h(0)
circuit.measure(0, 0)

simulator = AerSimulator()
compiled_circuit = transpile(circuit, simulator)
job = simulator.run(compiled_circuit, shots=1_000)
result = job.result()
counts = result.get_counts()

print(counts)

The shots argument controls how many times the circuit is sampled. The result is a dictionary whose keys represent measured bit strings and whose values represent the number of times each string appeared. For this circuit, the output should normally contain entries for both 0 and 1, although exact counts vary from run to run.

Transpilation converts a circuit into an instruction sequence suitable for the selected target. Even when a small circuit looks ready to execute, keeping transpilation in the workflow prepares you for devices with restricted gate sets, connectivity, or instruction requirements.

Scenario 3: Add a second qubit and test correlation

To move beyond a single independent measurement, create a Bell-state circuit:

from qiskit import QuantumCircuit, transpile
from qiskit_aer import AerSimulator

circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure([0, 1], [0, 1])

simulator = AerSimulator()
compiled_circuit = transpile(circuit, simulator)
result = simulator.run(compiled_circuit, shots=1_000).result()
print(result.get_counts())

The Hadamard gate creates a superposition on qubit 0, and the controlled-X gate links the two qubits. In an ideal simulation, the measured strings should be concentrated on two matching outcomes rather than spread evenly across all four possible two-bit strings. Bit-string display order can be confusing, so verify how your installed Qiskit version maps classical registers and printed keys before interpreting larger circuits.

Scenario 4: Prepare for cloud execution

A cloud quantum workflow adds account authentication, backend selection, queue considerations, and device-specific compilation. The exact IBM Quantum and provider APIs may change, so do not copy an old account or backend snippet without checking the current provider documentation. The portable part of your program is the circuit itself; the provider-specific part should be isolated in a small execution module.

Before submitting remotely, run the circuit locally, inspect its measurements, and confirm that the selected backend supports the required qubit count and operations. Expect hardware results to differ from ideal simulation because real devices introduce noise, calibration effects, and connectivity constraints.

For a broader comparison of local and cloud options, see Qiskit Aer, Cirq, PennyLane, and cloud backends.

What to double-check

  • Environment: Confirm that the terminal is using the intended virtual environment with python --version and python -m pip show qiskit.
  • Package boundaries: The local Aer simulator is installed separately from the core Qiskit package. An import error for qiskit_aer usually means the provider is missing or installed in a different environment.
  • API version: Check the installed package documentation when an example uses a provider, primitive, sampler, or runtime service. Qiskit execution APIs have evolved, and an older tutorial may use classes no longer recommended for a new project.
  • Measurements: A circuit without measurements may return a state representation or primitive-specific result, not the counts dictionary used in this tutorial.
  • Target compatibility: Transpile for the actual simulator or backend rather than assuming every gate is natively supported.
  • Reproducibility: Record package versions, the number of shots, backend name, transpilation options, and any seed used for a test run.

When choosing between SDKs, compare the execution model and debugging experience rather than treating one framework as universally best. The Qiskit Aer, Cirq, and PennyLane simulator comparison provides useful context for developers evaluating alternatives.

Common mistakes

Confusing superposition with two simultaneous classical values

A measurement produces a classical outcome. Superposition describes the quantum state before measurement and the probabilities associated with possible outcomes; it does not mean that a program prints both values from one shot.

Expecting identical counts on every run

Sampling is statistical. Two executions with the same circuit and shot count can produce different distributions. Compare the overall pattern and use enough shots for the question you are asking.

Skipping transpilation

A circuit that works conceptually may not match a device's supported gates or coupling map. Treat transpilation as a normal compilation stage, not an optional cleanup step.

Copying cloud credentials into source code

Keep tokens and account credentials out of notebooks, public repositories, and error logs. Prefer the provider's current authentication guidance and environment-level secret handling.

Debugging hardware before validating the simulator version

First prove that the circuit and measurement interpretation work locally. Then compare simulator and hardware results, documenting which differences may come from noise or backend constraints.

When to revisit

Return to this checklist whenever you create a new environment, upgrade Qiskit or Aer, change execution primitives, or move from local simulation to cloud hardware. Recheck provider authentication and backend-selection instructions immediately before a remote run because those workflows are more likely to change than the basic circuit syntax.

Before starting a small project, complete this practical sequence:

  1. Create a clean environment and record installed package versions.
  2. Build a one-qubit circuit with an explicit measurement.
  3. Run it locally for a known number of shots and inspect counts.
  4. Add a second circuit that tests correlation or another clearly defined behavior.
  5. Transpile both circuits for the intended target.
  6. Only then test a cloud backend, recording the backend and execution settings.
  7. Compare results without assuming that hardware output should match an ideal simulator exactly.

Once this loop feels routine, continue with a focused project such as a small Grover search, a variational optimization experiment, or a noise comparison. Keep the circuit, environment notes, and result interpretation together. That habit will remain useful as Qiskit interfaces and quantum backends change.

Related Topics

#Qiskit#quantum programming#quantum circuits#beginner tutorial#IBM Quantum#Python#developer guides
J

JustQubit Editorial Team

Quantum Computing Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.