Visualizations (qiskit.visualization)

The visualization module contain functions that visualizes measurement outcome counts, quantum states, circuits, pulses, devices and more.

To use visualization functions, you are required to install visualization optionals to your development environment:

pip install 'qiskit[visualization]'

Common Keyword Arguments

Many of the figures created by visualization functions in this module are created by Matplotlib and accept a subset of the following common arguments. Consult the individual documentation for exact details.

  • title (str): a text string to use for the plot title.

  • legend (list): a list of strings to use for labels of the data.

  • figsize (tuple): figure size in inches .

  • color (list): a list of strings for plotting.

  • ax (matplotlib.axes.Axes): An optional Axes object to be used for the visualization output. If none is specified a new matplotlib.figure.Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant.

  • filename (str): file path to save image to.

The following example demonstrates the common usage of these arguments:

from qiskit.visualization import plot_histogram

counts1 = {'00': 499, '11': 501}
counts2 = {'00': 511, '11': 489}

data = [counts1, counts2]

You can specify legend, title, figsize and color by passing to the kwargs.

legend = ['First execution', 'Second execution']
title = 'New histogram'
figsize = (10,10)
plot_histogram(data, legend=legend, title=title, figsize=figsize, color=color)

You can save the figure to file either by passing the file name to filename kwarg or use matplotlib.figure.Figure.savefig method.

plot_histogram(data, filename='new_hist.png')

hist = plot_histogram(data)

Counts Visualizations

This section contains functions that visualize measurement outcome counts.

plot_histogram(data[, figsize, color, ...])

Plot a histogram of input counts data.

Example Usage

Here is an example of using plot_histogram() to visualize measurement outcome counts:

from qiskit.visualization import plot_histogram

counts = {"00": 501, "11": 499}

The data can be a dictionary with bit string as key and counts as value, or more commonly a Counts object obtained from get_counts().

Distribution Visualizations

This section contains functions that visualize sampled distributions.

plot_distribution(data[, figsize, color, ...])

Plot a distribution from input sampled data.

State Visualizations

This section contains functions that visualize quantum states.

plot_bloch_vector(bloch[, title, ax, ...])

Plot the Bloch sphere.

plot_bloch_multivector(state[, title, ...])

Plot a Bloch sphere for each qubit.

plot_state_city(state[, title, figsize, ...])

Plot the cityscape of quantum state.

plot_state_hinton(state[, title, figsize, ...])

Plot a hinton diagram for the density matrix of a quantum state.

plot_state_paulivec(state[, title, figsize, ...])

Plot the paulivec representation of a quantum state.

plot_state_qsphere(state[, figsize, ax, ...])

Plot the qsphere representation of a quantum state.

Example Usage

Here is an example of using plot_state_city() to visualize a quantum state:

from qiskit.visualization import plot_state_city

state = [[ 0.75  , 0.433j],
         [-0.433j, 0.25  ]]

The state can be array-like list of lists, numpy.array, or more commonly Statevector or DensityMatrix objects obtained from a QuantumCircuit:

from qiskit import QuantumCircuit
from qiskit.quantum_info import Statevector, DensityMatrix

qc = QuantumCircuit(2)

# plot using a Statevector
state = Statevector(qc)
# plot using a DensityMatrix
state = DensityMatrix(qc)

You can find code examples for each visualization functions on the individual function API page.

Device Visualizations

plot_gate_map(backend[, figsize, ...])

Plots the gate map of a device.

plot_error_map(backend[, figsize, ...])

Plots the error map of a given backend.

plot_circuit_layout(circuit, backend[, ...])

Plot the layout of a circuit transpiled for a given target backend.

plot_coupling_map(num_qubits, ...[, ...])

Plots an arbitrary coupling map of qubits (embedded in a plane).

Circuit Visualizations

circuit_drawer(circuit[, scale, filename, ...])

Draw the quantum circuit.


Creates a Default Style dictionary

DAG Visualizations

dag_drawer(dag[, scale, filename, style])

Plot the directed acyclic graph (dag) to represent operation dependencies in a quantum circuit.

Pass Manager Visualizations

pass_manager_drawer(pass_manager[, ...])

Draws the pass manager.

Pulse Visualizations

draw(program[, style, backend, time_range, ...])

Generate visualization data for pulse programs.


Standard pulse stylesheet.


Simple pulse stylesheet without channel notation.


Pulse stylesheet for pulse programmers.

Timeline Visualizations

timeline_drawer(program[, style, ...])

Generate visualization data for scheduled circuit programs.

draw(program[, style, time_range, ...])

Generate visualization data for scheduled circuit programs.

Single Qubit State Transition Visualizations

visualize_transition(circuit[, trace, ...])

Creates animation showing transitions between states of a single qubit by applying quantum gates.

Array/Matrix Visualizations

array_to_latex(array[, precision, prefix, ...])

Latex representation of a complex numpy array (with dimension 1 or 2)



For visualization specific errors.