Skip to main contentIBM Quantum Documentation
You are viewing the API reference for an old version of Qiskit SDK. Switch to latest version


circuit_drawer(circuit, scale=None, filename=None, style=None, output=None, interactive=False, plot_barriers=True, reverse_bits=None, justify=None, vertical_compression='medium', idle_wires=True, with_layout=True, fold=None, ax=None, initial_state=False, cregbundle=None, wire_order=None)

GitHub(opens in a new tab)

Draw the quantum circuit. Use the output parameter to choose the drawing format:

text: ASCII art TextDrawing that can be printed in the console.

matplotlib: images with color rendered purely in Python.

latex: high-quality images compiled via latex.

latex_source: raw uncompiled latex output.


  • circuit (QuantumCircuit) – the quantum circuit to draw
  • scale (float) – scale of image to draw (shrink if < 1.0). Only used by the mpl, latex and latex_source outputs. Defaults to 1.0.
  • filename (str) – file path to save image to. Defaults to None.
  • style (dict or str) – dictionary of style or file name of style json file. This option is only used by the mpl or latex output type. If style is a str, it is used as the path to a json file which contains a style dict. The file will be opened, parsed, and then any style elements in the dict will replace the default values in the input dict. A file to be loaded must end in .json, but the name entered here can omit .json. For example, style='iqx.json' or style='iqx'. If style is a dict and the 'name' key is set, that name will be used to load a json file, followed by loading the other items in the style dict. For example, style={'name': 'iqx'}. If style is not a str and name is not a key in the style dict, then the default value from the user config file (usually ~/.qiskit/settings.conf) will be used, for example, circuit_mpl_style = iqx. If none of these are set, the default style will be used. The search path for style json files can be specified in the user config, for example, circuit_mpl_style_path = /home/user/styles:/home/user. See: DefaultStyle for more information on the contents.
  • output (str) – select the output method to use for drawing the circuit. Valid choices are text, mpl, latex, latex_source. By default the text drawer is used unless the user config file (usually ~/.qiskit/settings.conf) has an alternative backend set as the default. For example, circuit_drawer = latex. If the output kwarg is set, that backend will always be used over the default in the user config file.
  • interactive (bool) – when set to true, show the circuit in a new window (for mpl this depends on the matplotlib backend being used supporting this). Note when used with either the text or the latex_source output type this has no effect and will be silently ignored. Defaults to False.
  • reverse_bits (bool) – when set to True, reverse the bit order inside registers for the output visualization. Defaults to False unless the user config file (usually ~/.qiskit/settings.conf) has an alternative value set. For example, circuit_reverse_bits = True.
  • plot_barriers (bool) – enable/disable drawing barriers in the output circuit. Defaults to True.
  • justify (string) – options are left, right or none. If anything else is supplied, it defaults to left justified. It refers to where gates should be placed in the output circuit if there is an option. none results in each gate being placed in its own column.
  • vertical_compression (string) – high, medium or low. It merges the lines generated by the text output so the drawing will take less vertical room. Default is medium. Only used by the text output, will be silently ignored otherwise.
  • idle_wires (bool) – include idle wires (wires with no circuit elements) in output visualization. Default is True.
  • with_layout (bool) – include layout information, with labels on the physical layout. Default is True.
  • fold (int) – sets pagination. It can be disabled using -1. In text, sets the length of the lines. This is useful when the drawing does not fit in the console. If None (default), it will try to guess the console width using shutil.get_terminal_size(). However, if running in jupyter, the default line length is set to 80 characters. In mpl, it is the number of (visual) layers before folding. Default is 25.
  • ax (matplotlib.axes.Axes) – Only used by the mpl backend. An optional Axes object to be used for the visualization output. If none is specified, a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant.
  • initial_state (bool) – Optional. Adds |0> in the beginning of the wire. Default is False.
  • cregbundle (bool) – Optional. If set True, bundle classical registers into a single wire. Default is true if possible, and false if a block instruction needs to access an individual bit from a register.
  • wire_order (list) – Optional. A list of integers used to reorder the display of the bits. The list must have an entry for every bit with the bits in the range 0 to (num_qubits + num_clbits).


TextDrawing or matplotlib.figure or PIL.Image or str:

  • TextDrawing (output=’text’)

    A drawing that can be printed as ascii art.

  • matplotlib.figure.Figure (output=’mpl’)

    A matplotlib figure object for the circuit diagram.

  • PIL.Image (output=’latex’)

    An in-memory representation of the image of the circuit diagram.

  • str (output=’latex_source’)

    The LaTeX source code for visualizing the circuit diagram.


  • VisualizationError – when an invalid output method is selected
  • MissingOptionalLibraryError – when the output methods requires non-installed libraries.


from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
from import circuit_drawer
q = QuantumRegister(1)
c = ClassicalRegister(1)
qc = QuantumCircuit(q, c)
qc.measure(q, c)
circuit_drawer(qc, output='mpl', style={'backgroundcolor': '#EEEEEE'})

(Source code, png, hires.png, pdf)

Was this page helpful?
Report a bug or request content on GitHub.