Hello World in Qiskit

Classical computers store information as bits that are always either 0 or 1. Quantum computers use qubits, which can exist in a combination of 0 and 1 at the same time. This lets quantum algorithms explore many possibilities simultaneously and solve certain problems that are intractable for classical machines. Qiskit is IBM’s open-source Python library that makes quantum programming accessible: you write Python code, Qiskit translates it into quantum operations, and you can run those operations on a local simulator or on real quantum hardware.

A “Hello World” in quantum computing does not print text. Instead, it demonstrates the two properties that make quantum computers fundamentally different from classical ones: superposition (a qubit existing in a combination of 0 and 1 at the same time) and entanglement (two qubits whose measurement outcomes are correlated in a way that classical probability cannot explain). We will build a Bell state, the simplest circuit that shows both properties at once.

Installation

To begin, install Qiskit and the Aer simulator:

pip install qiskit qiskit-aer

qiskit-aer is a local simulator that runs on your computer. It lets you test quantum circuits without needing access to real quantum hardware, and for small circuits it produces mathematically perfect results.

Example 1: Bell State (Two Qubits)

A Bell state uses two gates in sequence: a Hadamard gate (which creates superposition) followed by a CNOT gate (which creates entanglement). Here is the complete program:

from qiskit import QuantumCircuit, transpile
from qiskit_aer import AerSimulator

# Create a circuit with 2 qubits and 2 classical bits
circuit = QuantumCircuit(2, 2)

# Put qubit 0 into superposition
circuit.h(0)

# Entangle qubit 0 and qubit 1
circuit.cx(0, 1)

# Measure both qubits
circuit.measure([0, 1], [0, 1])

# Run on the local simulator
simulator = AerSimulator()
compiled = transpile(circuit, simulator)
job = simulator.run(compiled, shots=1024)
counts = job.result().get_counts()

print("Bell State Results:", counts)
print(circuit.draw(output='text'))

Line-by-Line Walkthrough

QuantumCircuit(2, 2) creates a quantum circuit with 2 qubits and 2 classical bits. The qubits are where the quantum computation happens. The classical bits are ordinary 0/1 storage where measurement results get recorded. Both qubits start in state |0>.

circuit.h(0) applies the Hadamard gate to qubit 0. The Hadamard gate transforms |0> into an equal superposition: (|0> + |1>)/sqrt(2). In plain terms, qubit 0 is now in a state where it is both 0 and 1 at the same time. If you measured qubit 0 right now, you would get 0 or 1 each with exactly 50% probability. At this point, qubit 1 is still in state |0>, and the two qubits are independent of each other.

circuit.cx(0, 1) applies the CNOT (Controlled-NOT) gate. Qubit 0 is the “control” and qubit 1 is the “target.” The CNOT flips the target qubit if the control qubit is |1>, and does nothing if the control qubit is |0>. Because qubit 0 is in superposition, something remarkable happens: the CNOT creates an entangled state where qubit 1 becomes correlated with qubit 0. The combined two-qubit state is now (|00> + |11>)/sqrt(2). You can no longer describe each qubit independently. They are a single entangled system.

circuit.measure([0, 1], [0, 1]) measures both qubits and stores the results in the classical bits. Measurement collapses the quantum state into a definite classical outcome. The first argument [0, 1] lists which qubits to measure, and the second argument [0, 1] lists which classical bits receive the results.

transpile(circuit, simulator) compiles the circuit for the target backend. The simulator accepts all standard gates directly, so for this simple circuit the transpiler has little work to do. When targeting real hardware with limited gate sets and qubit connectivity, this step becomes essential.

simulator.run(compiled, shots=1024) runs the circuit 1024 times. Each run is called a “shot.” The simulator performs the quantum operations and measurement independently each time, collecting statistics across all shots.

Expected Output

Bell State Results: {'00': ~512, '11': ~512}

     ┌───┐     ┌─┐   
q_0: ┤ H ├──■──┤M├───
     └───┘┌─┴─┐└╥┘┌─┐
q_1: ─────┤ X ├─╫─┤M├
          └───┘ ║ └╥┘
c: 2/═════════════╩══╩═
              0  1 

The results show only 00 and 11, each appearing roughly 512 times out of 1024 shots. You never see 01 or 10.

Why does entanglement cause this? On each shot, the measurement randomly collapses the superposition to either |00> or |11>. The qubit pair is in a superposition of both qubits being 0 and both qubits being 1, with no component where they disagree. So when the state collapses, the outcomes are always the same for both qubits.

This 100% correlation is stronger than anything classical probability can produce. If you had two classical random bits that were each independently 50/50, you would see all four outcomes (00, 01, 10, 11) with roughly equal probability, 25% each. You could also classically “rig” two coins to always match, but then they would not be individually random. The Bell state achieves both: each qubit is individually random (50/50), yet they always agree. That combination is uniquely quantum.

The ~50/50 split between 00 and 11 confirms superposition. The absence of 01 and 10 confirms entanglement. Together, these two facts are the “Hello World” of quantum computing.

Reading the Circuit Diagram

The ASCII diagram printed by circuit.draw() reads left to right, like a timeline. Each horizontal line represents a qubit or a classical register:

• q_0: and q_1: are the two qubits. Operations appear as labeled boxes on these lines.
• c: 2/ is the classical register with 2 bits. The double line (═) distinguishes it from the quantum wires.
• ┤ H ├ is the Hadamard gate acting on qubit 0.
• ──■── is the control dot of the CNOT gate, sitting on qubit 0 (the control qubit).
• ┤ X ├ is the target of the CNOT gate, sitting on qubit 1. The vertical line connecting the dot to the X shows they are part of the same two-qubit gate.
• ┤M├ is a measurement operation. The double line descending from it shows the result being sent to a classical bit.
• ╩ at the bottom shows where each measurement result lands in the classical register. The numbers 0 and 1 label the classical bit positions.

Gates further to the left happen first. In this circuit, the Hadamard happens before the CNOT, and the measurements happen last.

Example 2: Single Qubit in Superposition

For an even simpler starting point, consider a single qubit. This is the smallest possible quantum program:

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

# 1 qubit, 1 classical bit
circuit = QuantumCircuit(1, 1)

# Put the qubit into superposition
circuit.h(0)

# Measure
circuit.measure(0, 0)

# Run 1024 shots
job = AerSimulator().run(circuit, shots=1024)
counts = job.result().get_counts()
print("Superposition Results:", counts)

Expected Output

Superposition Results: {'0': 507, '1': 517}

The Hadamard gate puts the qubit into an equal superposition of |0> and |1>. When you measure, the superposition collapses randomly to one outcome or the other, each with 50% probability. Over 1024 shots, you see a roughly even split.

This is a quantum random number generator. The randomness is not pseudo-random like a classical computer’s random() function, which uses a deterministic algorithm to produce numbers that merely look random. Quantum randomness is fundamentally unpredictable, arising from the laws of physics. No algorithm, no matter how clever, can predict which outcome a given shot will produce.

The exact counts vary each time you run the program. You will not get exactly 512 and 512, just as flipping a fair coin 1024 times will not land on heads exactly 512 times. Statistical fluctuations are normal.

Running on Real Quantum Hardware

Once you are comfortable with the simulator, you can run your circuits on a physical quantum processor. Create a free account at quantum.ibm.com, then copy your API token from the dashboard.

from qiskit_ibm_runtime import QiskitRuntimeService

# Save your credentials (only need to do this once)
QiskitRuntimeService.save_account(channel="ibm_quantum", token="YOUR_TOKEN")

# Connect and pick the least busy device
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

Replace "YOUR_TOKEN" with the API token from your IBM Quantum dashboard. The save_account call stores your credentials locally so you only need to run it once.

When you submit a circuit to real hardware, several things happen differently from the simulator:

1. Your job enters a queue. Depending on how many other users are submitting jobs, you might wait anywhere from a few seconds to several hours. Free-tier accounts share device time with many other researchers and learners.

2. Real hardware has noise. Physical qubits are not perfect. Gates have small error rates, qubits can lose their quantum state (decoherence), and measurements occasionally give the wrong answer. For the Bell state, this means you will likely see small counts of 01 and 10 in addition to the expected 00 and 11. That is normal and expected. A typical result from real hardware might look like {'00': 480, '11': 475, '01': 35, '10': 34}.

3. Transpilation matters more. Real devices only support certain gates natively and have limited connectivity between qubits. The transpiler rewrites your circuit to fit the hardware’s constraints, potentially adding extra gates. More gates means more accumulated noise.

Always develop and test your circuits on the Aer simulator first. Move to real hardware once you are confident the circuit logic is correct and you want to see how it behaves on an actual quantum processor.

What to Learn Next

This tutorial covered the bare essentials: one gate (Hadamard), one two-qubit gate (CNOT), measurement, and running on a simulator. Quantum computing goes much deeper from here.

For a more thorough introduction that covers additional gates, circuit composition, and visualization tools, see our Getting Started with Qiskit tutorial.

From there, you can explore:

• Building Your First Quantum Circuit for hands-on practice with more gate types
• Quantum Teleportation in Qiskit to see entanglement used as a resource
• Qiskit Visualization Tools for richer ways to inspect your circuits and results