Qiskit Tutorial: Write and Run Your First Program on a Real IBM Quantum Computer

What Is Qiskit?

Qiskit is IBM’s free, open-source Python toolkit for building quantum circuits and running them on simulators or on IBM’s real quantum computers. You don’t need a physics degree or a lab , just Python and a browser.

If you want the deeper mechanics of qubits, superposition, and phase before diving into code, see [Internal link: What Is Quantum Computing?]. For this tutorial, the important point is simpler: Qiskit turns a sequence of quantum operations into something you can write, run, and inspect like any other Python program.

What You Need Before You Start

You don’t need much to follow along, but a few things will make the difference between a smooth first run and a frustrating one.

• Python 3.10 or later installed on your machine
• Basic comfort with the command line (running pip install, activating a virtual environment)
• A free IBM Quantum account (covered in the next section)

No physics background is required for this tutorial. One honest caveat: if you’ve never written any Python before, learn that first. Trying to pick up Python and Qiskit’s syntax at the same time will make this harder than it needs to be.

Creating Your Free IBM Quantum Account

You’ll need an IBM Quantum account before you can run anything on real hardware.

1. Go to IBM Quantum Platform and sign up or log in.
2. Generate your API key (also called an API token) from your account dashboard.
3. Copy it somewhere safe , never paste your token into a public notebook, a shared script, or a GitHub repo.Anyone with your token can run jobs (and burn your free minutes) on your account.
4. From the Instances page, copy the CRN of the instance you want to use.

Visual suggestion: Screenshot of the IBM Quantum Platform account dashboard with the API token field visible.Placement: Directly below step 2 above. Alt text: IBM Quantum account page showing where to find your API token, token blurred out.

Free-tier honesty check: as of IBM’s own pricing update on 16 March 2026, the Open Plan gives you 10 minutes of real QPU runtime every 28 days, free, no credit card required. Active users who’ve used at least 20 minutes within a 12-month period can opt into a one-time bump to 180 minutes over the following year. Limits change , check IBM’s current plans page before relying on a specific number.

For this tutorial, 10 minutes is plenty. The circuit you’ll build takes a fraction of a second of actual QPU time; most of your “wait” is queue time, not runtime, which is covered later.

No Installation? Start with IBM Quantum Composer

Before you install anything, it’s worth seeing a working circuit in two minutes flat.

IBM Quantum Composer is a drag-and-drop circuit builder that runs entirely in your browser, at quantum.cloud.ibm.com/composer. No installation, no Python required.

Drag a gate onto a qubit’s wire, and the state visualization updates immediately. This is the fastest way to build intuition for one gate in particular: the Hadamard gate, which turns a qubit that’s definitely 0 into an even mix of 0 and 1 , the building block for everything that follows in this tutorial. [Internal link: Quantum Gates Explained] covers what the Hadamard gate and its neighbors actually do, in more depth than needed here.

Visual suggestion: Screenshot of a gate mid-drag onto a circuit wire in Composer. Placement: After the paragraph introducing Composer. Alt text: Building a quantum circuit by dragging gates in IBM Quantum Composer.

A reader who builds a working circuit here in two minutes is far more likely to stick with the harder, code-based sections below.

Installing Qiskit

If you’re ready to move from Composer into code, here’s the install path and where most tutorials, including outdated ones still ranking in search results, start causing errors.

Setting Up a Virtual Environment (Do This First)

Create a dedicated virtual environment before installing anything:

python3 -m venv qiskit-env

source qiskit-env/bin/activate   # On Windows: qiskit-env\Scripts\activate

This keeps Qiskit’s dependencies from colliding with other Python projects on your machine. This single step prevents the majority of the installation errors covered below.

Installing Qiskit with Pip

Install both the core SDK and the runtime client you’ll need to reach real hardware:

pip install qiskit[all]

pip install qiskit-ibm-runtime

Confirm it worked:

import qiskit

print(qiskit.__version__)

You should see 2.5.x or later. If you’re on an older 1.x version, expect some of the syntax below to differ ,check the Qiskit migration notes on GitHub before continuing.

Using Qiskit in Jupyter Notebook

Most readers will want Jupyter, since circuit diagrams and histograms render inline:

pip install jupyter

jupyter notebook

Common Installation Errors and How to Fix Them

Most installation problems trace back to one of a handful of causes. Here’s what actually shows up, and why.

Error	Likely cause	Fix
ModuleNotFoundError: No module named ‘qiskit’	Installed outside your active virtual environment	Activate the environment, then reinstall
Circuit drawing fails / blank output	Missing visualization extras	Reinstall with pip install qiskit[all]
pip: command not found	Using Python 3 without pip3 alias	Try pip3 install qiskit instead
Old code using execute() or IBMQ.load_account() fails	Code written for Qiskit 1.x or earlier	These functions were removed; use SamplerV2/EstimatorV2 from qiskit_ibm_runtime instead
qiskit_ibm_provider import errors	Following a tutorial referencing the deprecated provider package	Use qiskit-ibm-runtime, which replaced it

That fourth row is worth flagging directly: if you’re following a Medium post or GitHub example from before 2025, it’s very likely broken by Qiskit’s version changes, not by anything you did wrong.

Building Your First Quantum Circuit

Now for the actual quantum program: a two-qubit Bell state, the standard “hello world” of quantum computing.

The Code, Line by Line

from qiskit import QuantumCircuit

# Create a circuit with 2 qubits and 2 classical bits (to store measurement results)

qc = QuantumCircuit(2, 2)

# Apply a Hadamard gate to qubit 0 , puts it into superposition

qc.h(0)

# Apply a CNOT gate: flips qubit 1 only if qubit 0 measures as 1

qc.cx(0, 1)

# Measure both qubits into the classical bits

qc.measure([0, 1], [0, 1])

qc.draw(“mpl”)

The Hadamard gate creates superposition on qubit 0. The CNOT gate then entangles qubit 1 with it , the two qubits become correlated in a way that has no classical equivalent. [Internal link: Quantum Gates Explained] walks through exactly why CNOT is the gate that creates entanglement, if you want the mechanism rather than just the recipe.

What the Circuit Diagram Is Telling You

qc.draw(“mpl”) renders the circuit as a diagram, read left to right like sheet music: each horizontal line is a qubit, and each symbol is an operation applied to it in sequence.

Visual suggestion: The rendered circuit diagram from the code above. Placement: Immediately after the code block. Alt text: Two-qubit Bell state circuit drawn by Qiskit, showing a Hadamard gate on qubit 0 and a CNOT gate entangling qubit 1.

What Result You Should Expect

Once measured, this circuit should produce roughly 50% 00 and 50% 11, with almost no 01 or 10. That specific, almost-clean 50/50 split is what makes the next two sections : simulator, then real hardware  worth comparing directly.

Running It on a Simulator First

Always simulate before you spend real queue time. It’s instant, it’s free, and it confirms your circuit is actually correct before hardware noise gets involved.

from qiskit.primitives import StatevectorSampler

sampler = StatevectorSampler()

result = sampler.run([qc], shots=1024).result()

counts = result[0].data.c.get_counts()

print(counts)

You’ll get something close to {’00’: 512, ’11’: 512} — a clean, near-perfect 50/50 split.

A simulator is a normal computer pretending to be a quantum computer. It’s not the real thing, which is exactly why the next section exists.

Running It on a Real IBM Quantum Computer

This is the part most Qiskit tutorials skip entirely. Here’s how to actually get your circuit onto a physical device.

Choosing a Backend

Rather than trusting a qubit count or device name from an article (hardware changes constantly), pull the current list and let Qiskit pick the least-busy option for you:

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService(

    token=”<your-api-key>”,

    instance=”<your-CRN>”,

)

backend = service.least_busy(operational=True, simulator=False)

print(backend.name)

Submitting Your Job

Real hardware requires transpiling your circuit into the gates that specific device actually supports, then submitting it through the Sampler primitive:

from qiskit.transpiler import generate_preset_pass_manager

from qiskit_ibm_runtime import SamplerV2 as Sampler

pm = generate_preset_pass_manager(backend=backend, optimization_level=1)

isa_circuit = pm.run(qc)

sampler = Sampler(mode=backend)

job = sampler.run([isa_circuit], shots=1024)

print(f”Job ID: {job.job_id()}”)

Save that job ID , you can use it to retrieve your results later, even if you close your notebook.

The Queue: What’s Happening While You Wait

Nobody covers this properly, and it’s the number one reason beginners think something’s broken.

You’re sharing a physical machine with everyone else using the Open Plan. Your job sits in a queue behind other jobs, and the wait can range from a couple of minutes to considerably longer depending on demand , there’s no fixed number worth quoting here, since it shifts hour to hour.

This is completely normal. You can close your laptop; the result will be waiting when you check back with your job ID.

Visual suggestion: Screenshot of a job’s status page on IBM Quantum Platform showing “Queued.” Placement: Directly after this section. Alt text: Qiskit job waiting in the IBM Quantum queue, showing job status as queued.

Reading Your Results and Why They’re Messy

This is the most useful 200 words on this page.

result = job.result()

counts = result[0].data.c.get_counts()

print(counts)

Your real output won’t be a clean 50/50. Expect something like {’00’: 460, ’11’: 470, ’01’: 48, ’10’: 46} — noticeable 01 and 10 counts that shouldn’t be there at all.

That’s not a bug in your code. Real qubits are physical objects. Heat, electromagnetic interference, and the simple passage of time cause them to lose their state gradually a process called decoherence  and every gate operation introduces a small chance of error. [Internal link: Quantum Error Correction] covers why this happens at the hardware level and what’s being done about it; the practical takeaway here is just that noise on real hardware is expected, not a sign you did something wrong.

Visual suggestion: Two histograms side by side , the clean simulator result and the noisier real-hardware result.Placement: Immediately after this section’s explanation. Alt text: Simulator results compared with noisy results from a real IBM quantum computer, showing near-perfect 50/50 split versus a noisier real distribution.

Simulator vs Real Hardware: What Actually Differs

Seeing the two side by side makes the trade-off concrete, and it’s the single most useful reference on this page if you only remember one table.

	Simulator	Real QPU
Speed	Instant	Minutes to hours (mostly queue time)
Cost	Free, unlimited	Free tier limited to 10 min / 28 days
Accuracy	Matches theory exactly	Noisy — decoherence and gate errors
Qubits available	Limited only by your computer’s memory	Fixed by the physical device
Best for	Debugging circuit logic before committing queue time	Confirming your circuit works on real physics

Neither replaces the other. Simulate to check your logic; run on hardware to see what real quantum behavior actually looks like.

Ready to go beyond your first Qiskit program?

Running your first quantum circuit is just the beginning. Take the next step with the 

Certification in Applied Quantum Computing & AI by CEP, IIT Delhi ,a structured, hands-on programme covering quantum computing, Qiskit, quantum algorithms, optimisation, AI/ML, cybersecurity, and real quantum systems.

Build deeper quantum skills. Work on real applications. Create portfolio-ready projects.

Where to Go Next with Qiskit

Treat everything above as programming practice and a genuine CV talking point not, on its own, a career pivot. [Internal link: Quantum Computing Jobs] covers the honest picture of what quantum roles actually require right now, and it’s worth reading before assuming this tutorial is step one of a job path.

Practical next steps that build directly on what you just did:

• Learn the common gates properly  [Internal link: Quantum Gates Explained]
• Work through IBM Quantum Learning, the official replacement for the retired Textbook
• Try a real algorithm next  [Internal link: Grover’s Algorithm] builds directly on the circuit patterns used here
• Explore the Qiskit community and source code on GitHub

Frequently Asked Questions