Build, edit, and inspect quantum circuits


Follow these steps to build a quantum circuits:

1. Open IBM Quantum Composer

2. Create your circuit: either drag-and-drop operations or enter OpenQASM code. Optionally, create a custom operation in OpenQASM.

3. Inspect your circuit’s components using Circuit Inspector.

Continue reading for more details.

Open IBM Quantum Composer

  1. (Optional) If you are not currently signed in to IBM Quantum, select Sign in in the upper right corner. Then, you can either sign in or Create an IBMid account.

    If you don’t sign in, the visualizations automatically show simulated results for up to four qubits. If you want to run your circuit on a quantum system or simulator, or if you want to visualize a circuit that has more than four qubits, you must sign in.

  2. Open IBM Quantum Composer by clicking the Application switcher ( switcher ) on the upper left corner, then click Composer. The workspace displays an untitled empty circuit.

  3. Name your circuit by clicking on the words Untitled circuit and typing in a name for your circuit. Click the checkmark to save the name.

  4. (Optional) Customize your workspace:

  • Use the View menu to change from the default theme to a monochrome theme. You can also select which panels to include on your workspace, then use the menu in the right corner of any panel to access options for further customization. The options to show or hide phase disks, choose the alignment of the qubits on your circuit, and reset the workspace to the default are in the View menu as well.

  • Open your account settings ( account ) to switch between dark and light workspace themes.

  • If you are signed in, the Files panel displays by default. You can close it by clicking the Files icon files.

To build a circuit, you can either drag-and-drop operations, or you can enter OpenQASM code into the code editor. Your circuit is automatically saved every time you make a change.

Build your circuit with drag-and-drop

Operations catalog

Drag and drop operations from the operations catalog onto the quantum and classical registers. Start typing in the search window to quickly find an operation.

Collapse and expand the operations catalog by clicking the icon in the upper right corner of the operations panel. You can also switch between an expanded or condensed view of the operations by using the icons next to the search window.

Right-click an operation icon and select Info to view the definition of an operation, along with its QASM reference.

To undo or redo, use the curved arrows in the toolbar.


Choose Freeform alignment to place operations anywhere on the circuit. For a more compact view of your circuit, choose Left alignment. To see the order in which operations will execute, choose Layers alignment, which will apply left alignment and add column delineators that indicate the execution order, from left to right and top to bottom.

Once operations are placed on your circuit, you can continue to drag and drop them to new positions.

Copy and paste

Click an operation and use the icons in the contextual menu to copy and paste it.

Select multiple operations

You can select several operations to copy and paste them, drag them to a new location, or group them into a custom unitary operation that displays in your operations catalog and functions as a single gate.

To select more than one operation, place your cursor just outside one of the operations, then click and drag across the area to select. Shift-click individual operations to select or deselect them. A dashed line outlines the set of operations you are selecting, and each operation that is actually part of the selection is outlined in blue.

For example, in the following image, the Hadamard gate on q1 and the CX gate are selected. The Hadamard gate on q0 is not selected.

A set of selected operations.

Select Copy from the contextual menu to copy the group.

Right-click menu options.

To paste the group of operations, right-click in the circuit and select Paste.

Build a custom operation using the group feature

To group several operations together and save them as a custom operation, first select the operations as described above, then select Group from the contextual menu. You are prompted to name the custom operation or you can accept the default name. Click OK, and the custom operation will be represented by a single box, both in your circuit and in the operations catalog.

You can now drag and drop the new operation throughout your circuit. Note that the operation is saved to this circuit but does not appear in the operations catalog for other circuits.

You can also build a custom operation directly in the OpenQASM code editor; see Create a custom operation in OpenQASM for more information.

Ungroup a custom or predefined operation

To ungroup the gates within a custom or predefined operation, click the operation on the Composer and select Ungroup from the contextual menu. You can now move the separate operations individually. When you ungroup an operation, each element in the former group executes independently, which may mean they execute in a different order from when they were grouped together.

Expand an operation’s definition

To view the operations that constitute a custom or predefined operation without ungrouping them, click Expand definition from the contextual menu to see the defining gates. Click the icon again to collapse the definition.

Rename or delete a custom operation

To rename or delete a custom operation, right-click the operation in the operations catalog and select Rename or Delete. Deleting a custom operation from the operations catalog also deletes any instances of it on your circuit; however, deleting a custom operation from the circuit does not delete it from the operations catalog.

Create a custom operation by grouping.

Add or remove registers

To add or remove quantum or classical registers, click Edit → Manage registers. You can increase or decrease the number of qubits or bits in your circuit and rename the registers. Click Ok to apply the changes. You can also simply click the register name (e.g., q[0]) and use the options in the contextual menu to quickly add or delete registers or qubits.

Add a conditional

To add a conditional to a gate, drag the if operation to the gate and set the parameters in the Edit operation panel that automatically opens. You can also double-click a gate to access the Edit operation panel, and set the conditional parameters that way.

Add a control modifier

A control modifier yields a gate whose original operation is now contingent on the state of the control qubit. For more details, right-click the control modifier symbol in the operations catalog, then click Info.

Drag the control modifier control to a gate in order to add a control to it. A dot appears on the control qubit and a line connects it to the target qubit. To edit which qubit is the control or target, click the gate and select the Edit operation icon (or double-click the gate) to open the Edit operation panel, then specify your parameters. From the Edit operation panel, you can also remove a control from a qubit by clicking the x next to the qubit name.

control modifier.

Visualize with phase disks throughout your circuit

To visualize the state of all qubits at any point in your circuit, drag the phase disk icon from the operations catalog and place it anywhere in your circuit. A column of barrier operations and a column of phase disks are added (one barrier operation and phase disk per qubit). Hover over each phase disk to read the state of the qubit at that point in the circuit. Note that adding the phase disks does not alter your circuit; they are merely a visualization tool.

Read more about the phase disk visualization here.

Export a circuit image

To export an image of your circuit, select File → Export. The Export options window opens, where you can choose a theme (light, dark, white on black, or black on white), a format (.svg or .png), and whether you want to apply a line wrap. After you’ve chosen your options, click Export.

Conditional reset

Several hardware systems can now perform conditional reset. If you have access to these systems, either through the IBM Quantum Network, or the Educators or Researchers programs, you can now initialize (or re-initialize) qubits in the |0\rangle state, through measurement followed by a conditional X gate. Conditional reset will be rolled out to more systems, including open-access systems, over time. Read these tutorials for more details:

Build your circuit with OpenQASM code


IBM Quantum Composer currently supports OpenQASM 2.0.

  • To open the code editor, click View → Panels → Code Editor.

  • See the Operations glossary for OpenQASM references to gates and other operations.

  • You can define your own custom operations; see Create a custom operation in OpenQASM.

  • For more information on using the OpenQASM language, including sample lines of code, see the original research paper, Open Quantum Assembly Language. The table of OpenQASM language statements from the paper is reproduced below. The OpenQASM grammar can be found in Appendix A of the paper.

OpenQASM language statements (version 2.0)





Denotes a file in OpenQASM format[a]


qreg name[size];

Declare a named register of qubits

qreg q[5];

creg name[size];

Declare a named register of bits

creg c[5];

include “filename”;

Open and parse another source file

include “”;

gate name(params) qargs

Declare a unitary gate

(see text of paper)

opaque name(params) qargs;

Declare an opaque gate

(see text of paper)

// comment text

Comment a line of text

// oops!

U(theta,phi,lambda) qubit\|qreg;

Apply built-in single-qubit gate(s)[b]

U(pi/2,2\*pi/3,0) q[0];

CX qubit\|qreg,qubit\|qreg;

Apply built-in CNOT gate(s)

CX q[0],q[1];

measure qubit\|qreg -> bit\|creg;

Make measurement(s) in Z basis

measure q -> c;

reset qubit\|qreg;

Prepare qubit(s) in |0\rangle

reset q[0];

gatename(params) qargs;

Apply a user-defined unitary gate

crz(pi/2) q[1],q[0];

if(creg==int) qop;

Conditionally apply quantum operation

if(c==5) CX q[0],q[1];

barrier qargs;

Prevent transformations across this source line

barrier q[0],q[1];

[a] This must appear as the first non-comment line of the file.

[b] The parameters theta, phi, and lambda are given by parameter expressions; for more information, see page 5 of the paper and Appendix A.

Create a custom operation in OpenQASM

You can define new unitary operations in the code editor (see the figure below for an example). The operations are applied using the statement name(params) qargs; just like the built-in operations. The parentheses are optional if there are no parameters.

To define a custom operation, enter it in the OpenQASM code editor using this format: gatename(params) qargs;. If you click +Add in the operations list, you will be prompted to enter a name for your custom operation, which you can then build in the code editor.

Once you have defined your custom operation, drag it onto the graphical editor and use the edit icon to fine-tune the parameters.

a) The gates to be included in the custom operation:


b) The code for the new operation:


c) The new operation in the graphical editor:


Inspect your circuit, step-by-step

The Circuit Inspector de-mystifies the inner workings of the circuits you create. It steps through a simulation of your circuit, one layer at a time, so that you can see the state of the qubits as the computation evolves.

Circuit Inspector.
  • In the View menu, select the panels for the visualizations that you want to use.

  • Click the Inspect toggle in the toolbar. Note that once the Circuit Inspector is toggled on, you cannot add any more operations until it is turned off again.

  • If you built your circuit with the Freeform alignment turned on, note that the Circuit Inspector automatically turns on the Left alignment.

  • To move step-by-step through visualizations of your circuit’s components, control the movement of the Circuit Inspector using the forward and rewind buttons.

    Controls to step forward and backward, and to jump to a circuit's beginning or end.

    Inspector controls, in order: jump to the beginning of a circuit, step backward, play from one break point to the next, step forward, jump to the end of a circuit.

  • To inspect only some operations, click the operations you want to be inspected, and a colored overlay appears over each that indicates they will be included when you run the Circuit Inspector. To unselect an operation, click on it again, and the overlay disappears.

  • To learn more about interpreting visualizations, see the Visualizations topic.

  • To close the Inspector and return to editing your circuit, click the Inspect toggle in the toolbar.

Randomness in the simulator

The simulator creates randomness by generating results based on a seed. The seed is the initial value introduced into the algorithm that generates pseudorandom numbers. You can see the seed number in a box above Quantum Composer. You can also set the seed yourself by changing the value in the box.

Run your circuit

When you are ready to run your circuit on a quantum system or simulator and interpret the results, continue to this topic: Run circuits and view results.