Skip to main contentIBM Quantum Learning

Code your first quantum circuit

Code your first quantum circuit in Quantum Lab, without downloading anything to your computer. While you can benefit from having some familiarity with Python(opens in a new tab) and linear algebra(opens in a new tab), you can get a sense of the big picture without those prerequisites.


If you already have some familiarity with Python or Jupyter notebooks, try the getting-started notebook(opens in a new tab) instead.

Working with the user interface

These tips will help you get started with the user interface. For more in-depth information, see the JupyterLab documentation(opens in a new tab).

  • You can view this page as a tab from within IBM Quantum Lab itself. In Quantum Lab, open the docs panel by selecting the Docs icon in the left-side navigation, then click Code your first circuit (under Quantum Lab user guide).
  • Use the command palette to search for and run JupyterLab commands. To open it, press Cmd/Ctrl + Shift + C.
  • Right-click to access actions for files, notebook cells, and so on.
  • To get back to the Launcher, click File -> New Launcher.
  • To open a new notebook prepopulated with Qiskit libraries, click File -> New -> Qiskit notebook.
  • To open a file, double-click the file in the File browser.
  • See Troubleshooting in IBM Quantum Lab if you have a problem.


Quantum circuits are the foundation of quantum computing. They are made up of quantum gates. When you run a quantum circuit, the gates manipulate qubits in the quantum computer.

To code any quantum circuit in Quantum Lab, you follow three high-level steps:

  1. Build: Design a quantum circuit that represents the problem you are considering.
  2. Execute: Run a circuits on a backend, either a system or a simulator.
  3. Analyze: Calculate summary statistics and visualize the results of your circuit jobs.

The following instructions guide you through building a circuit with example code in a Jupyter Notebook environment, executing your program, and analyzing the results.

Before you begin: Create a new notebook in Quantum Lab

  1. Go to IBM Quantum Lab(opens in a new tab) and sign in.
  2. On the Launcher tab, under Notebook, click Qiskit. The first cell in your new notebook imports Qiskit into your Jupyter Notebook environment.

Imported packages and functions

These lines are added to every new notebook in IBM Quantum Lab. Do not add them to your notebook.

The import lines import the basic elements (packages and functions) needed for your program. The following imports are the default imports for any new notebook in Quantum Lab, so they do not appear as a code snippet.

# Importing standard Qiskit modules and configuring account
from qiskit import QuantumCircuit, execute, Aer, IBMQ
from qiskit.compiler import transpile, assemble
from import *
from qiskit.visualization import *
from ibm_quantum_widgets import *
# Loading your IBM Quantum account(s)
provider = IBMQ.load_account()

The imports used are:

  • QuantumCircuit: Holds all your quantum operations; the instructions for the quantum system
  • execute: Runs your circuit
  • Aer: Handles simulator backends
  • qiskit.visualization: Enables data visualization, such as plot_histogram
  • ibm_quantum_widgets: Enables circuit editing and visualization that looks like Quantum Composer

Each code cell in the notebook must be run sequentially, starting with the first cell that imports Qiskit. To run a cell in a notebook, click Run or press Shift + Enter/Return.

Build a circuit

Copy this code into an empty cell in your notebook, then run it:

# Build
# Create a Quantum Circuit acting on the q register
circuit = QuantumCircuit(2, 2)
# Add a H gate on qubit 0
# Add a CX (CNOT) gate on control qubit 0 and target qubit 1, 1)
# Map the quantum measurement to the classical bits
circuit.measure([0,1], [0,1])


First, initialize two qubits in the zero state and two classical bits in the zero state in the quantum circuit called circuit:

circuit = QuantumCircuit(2, 2)

Next, add gates that manipulate the qubits in your circuit to form a Bell state:

In this state, there is a 50% chance of finding both qubits to have the value 0 and a 50% chance of finding both qubits to have the value 1.


  • QuantumCircuit.h(0): A Hadamard gate (H) on qubit 0, which puts it into a superposition state.
  •, 1): A controlled-NOT operation (CX) on control qubit 0 and target qubit 1, putting the qubits in an entangled state.
  • QuantumCircuit.measure([0,1], [0,1]): The first argument indexes the qubits; the second argument indexes the classical bits. The nth qubit’s measurement result will be stored in the nth classical bit.
circuit.h(0), 1)
circuit.measure([0,1], [0,1])

Execute the experiment

Copy this code into an empty cell in your notebook, then run it:

# Execute
# Use Aer's qasm_simulator
simulator = Aer.get_backend('qasm_simulator')
# Execute the circuit on the qasm simulator
job = execute(circuit, simulator, shots=1000)
# Grab results from the job
result = job.result()
# Return counts
counts = result.get_counts(circuit)
print("\nTotal count for 00 and 11 are:",counts)


You can run the experiment on either physical quantum systems or simulators. For this tutorial we are using a simulator, which is faster and uses fewer compute resources. Because of this, users will often verify their experiment on a simulator before sending it to an actual quantum system.

The following code calls Aer, a high-performance simulator that provides several backends(opens in a new tab) to achieve different simulation goals. In this tutorial, we use the qasm_simulator. Each run of this circuit will yield either the bit string 00 or 11.

The shots argument specifies how many times to run the circuit. The default number of shots is 1024.

simulator = Aer.get_backend('qasm_simulator')
job = execute(circuit, simulator, shots=1000)

Once you have a result object, you can access the counts via the method get_counts(circuit). This gives you the aggregate outcomes of your experiment.

As expected, the output bit string is '00' approximately 50 percent of the time. This simulator does not model noise. Any deviation from 50 percent is due to the small sample size.

result = job.result()
counts = result.get_counts(circuit)
print("\nTotal count for 00 and 11 are:",counts)

Analyze the experiment

3a. Visualize the circuit

Copy this code into an empty cell in your notebook, then run it:

# Visualize
# Import draw_circuit, then use it to draw the circuit
from ibm_quantum_widgets import draw_circuit
# Analyze
# Plot a histogram


There are several different tools you can use to visualize a circuit in one of the various styles used in textbooks and research articles. The following visualizations use a single-shot statevector simulator.

In this circuit, the qubits are ordered with qubit zero at the top and qubit one below it. The circuit is read from left to right, representing the passage of time.

To visualize a circuit with the IBM Quantum Composer look and feel, use the draw_circuit function.

from ibm_quantum_widgets import draw_circuit

Note: The following gates in Qiskit do not belong to and are not supported by the CircuitComposer widget or draw_circuit function. - ms(theta, qubits) - r(theta, phi, qubit) - rcccx(control_qubit1, control_qubit2, control_qubit3, target_qubit) - ryy(theta, qubit1, qubit2) - rzx(self, theta, qubit1, qubit2) - iswap(self, qubit1, qubit2) - mcu1(self, lam, control_qubits, target_qubit) - dcx(self, qubit1, qubit2)

To visualize a circuit that uses one of these gates, use QuantumCircuit.draw() by calling circuit.draw() instead.


3b. Plot a histogram

Copy this code into an empty cell in your notebook, then run it:

 # Plot a histogram


Qiskit provides many visualizations, including the function plot_histogram, to view your results.


The probabilities (relative frequencies) of observing the and states are computed by taking the respective counts and dividing by the total number of shots.

Next steps

Was this page helpful?