Visualization

Qiskit visualizes circuits, sampled counts, ideal states, and backend layouts. The local Matplotlib/text/Bloch examples were executed; LaTeX, notebook displays, and backend maps are illustrative. Plotting is analysis support, not a substitute for numerical validation.

Install Plotting Dependencies

uv pip install "qiskit[visualization]==2.5.2"

The text circuit drawer works with the core package. Matplotlib, Pillow, LaTeX helpers, and notebook integrations depend on the selected output.

Circuit Drawers

Text

from qiskit import QuantumCircuit

circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)

print(circuit.draw(output="text", fold=-1))

Text output is the most reliable choice for logs, tests, and terminal-only environments.

Matplotlib

figure = circuit.draw(
    output="mpl",
    style="iqp",
    fold=40,
    idle_wires=False,
)
figure.savefig(
    "circuit.svg",
    bbox_inches="tight",
)

Keep the returned Figure; calling savefig() on an unrelated current figure can save the wrong plot.

Useful options:

circuit.draw(
    output="mpl",
    reverse_bits=False,
    initial_state=True,
    plot_barriers=True,
    fold=30,
)

reverse_bits changes display order, not circuit semantics.

LaTeX

latex_image = circuit.draw(output="latex")
latex_source = circuit.draw(output="latex_source")

LaTeX rendering requires an appropriate local TeX installation. Prefer SVG from the Matplotlib drawer when a full TeX toolchain is unavailable.

Custom Circuit Styles

style = {
    "displaycolor": {
        "h": ("#648fff", "#ffffff"),
        "cx": ("#785ef0", "#ffffff"),
        "measure": ("#dc267f", "#ffffff"),
    },
    "fontsize": 11,
    "subfontsize": 8,
}

figure = circuit.draw(output="mpl", style=style)

Built-in style names can change. iqp and bw are useful starting points in Qiskit 2.5.

Use color plus labels or structure; do not make color the only way to distinguish operations.

Count Histograms

from qiskit.visualization import plot_histogram

figure = plot_histogram(
    counts,
    sort="value_desc",
    bar_labels=True,
    title="Bell-state samples",
)
figure.savefig(
    "counts.png",
    dpi=300,
    bbox_inches="tight",
)

Compare datasets:

figure = plot_histogram(
    [ideal_counts, noisy_counts, hardware_counts],
    legend=["ideal", "noise model", "hardware"],
    figsize=(10, 5),
)

Normalize explicitly when comparing runs with different shot counts:

def normalize_counts(counts):
    total = sum(counts.values())
    return {
        bitstring: count / total
        for bitstring, count in counts.items()
    }

Label whether bars are counts, frequencies, or quasi-probabilities. Sampler V2 returns shot data, not V1 quasi-distributions.

Statevector and Density-Matrix Plots

Construct ideal states only for circuits without measurements, resets, or unsupported classical control:

from qiskit.quantum_info import DensityMatrix, Statevector

state = Statevector.from_instruction(unitary_circuit)
density_matrix = DensityMatrix(state)

Available plotters:

from qiskit.visualization import (
    plot_bloch_multivector,
    plot_state_city,
    plot_state_hinton,
    plot_state_paulivec,
    plot_state_qsphere,
)

plot_bloch_multivector(state)
plot_state_city(density_matrix)
plot_state_hinton(density_matrix)
plot_state_paulivec(density_matrix)
plot_state_qsphere(state)

Dense state memory grows exponentially:

• statevector: \(2^n\) complex amplitudes,
• density matrix: \(4^n\) complex entries.

Do not construct a dense state solely to make a plot when the system size is not tractable.

Single Bloch Vector

from qiskit.quantum_info import Pauli, Statevector
from qiskit.visualization import plot_bloch_vector

state = Statevector.from_label("+")
figure = plot_bloch_vector(
    [float(state.expectation_value(Pauli(axis)).real) for axis in "XYZ"],
    title="|+>",
)

A reduced qubit from an entangled state may be mixed and appear inside the Bloch sphere. A per-qubit Bloch view does not show multipartite entanglement.

Backend Topology and Errors

from qiskit.visualization import plot_error_map, plot_gate_map

gate_map_figure = plot_gate_map(backend)
error_map_figure = plot_error_map(backend)

These plots reflect the backend snapshot exposed by the provider. Record the retrieval time and backend.

Plot a compiled circuit's physical placement:

from qiskit.visualization import plot_circuit_layout

layout_figure = plot_circuit_layout(
    isa_circuit,
    backend,
)

Use isa_circuit.layout for program logic. A plot is for inspection, not a machine-readable mapping.

Before-and-After Circuit Comparison

import matplotlib.pyplot as plt

figure, axes = plt.subplots(
    nrows=2,
    figsize=(14, 7),
    constrained_layout=True,
)

circuit.draw(
    output="mpl",
    ax=axes[0],
    fold=-1,
)
axes[0].set_title("Logical circuit")

isa_circuit.draw(
    output="mpl",
    ax=axes[1],
    fold=-1,
)
axes[1].set_title(
    f"ISA circuit on {backend.name}"
)

figure.savefig(
    "logical-vs-isa.svg",
    bbox_inches="tight",
)

For very wide circuits, save separate figures rather than shrinking labels until unreadable.

Parameter and Convergence Plots

Qiskit returns numerical arrays; use Matplotlib directly for scientific plots:

import matplotlib.pyplot as plt

figure, axis = plt.subplots()
axis.plot(iterations, objective_values, marker="o")
axis.set(
    xlabel="Objective evaluation",
    ylabel="Energy (hartree)",
    title="VQE convergence",
)
axis.grid(alpha=0.25)
figure.savefig(
    "vqe-convergence.svg",
    bbox_inches="tight",
)

Include uncertainty bars when repeated runs or estimator standard deviations are available:

axis.errorbar(
    parameter_values,
    expectation_values,
    yerr=standard_deviations,
    fmt="o-",
    capsize=3,
)

Do not interpret optimizer history as statistically independent samples.

Publication Output

Prefer vector formats for circuit diagrams and line art:

figure.savefig(
    "figure.svg",
    bbox_inches="tight",
    metadata={"Creator": "Qiskit 2.5 workflow"},
)
figure.savefig(
    "figure.pdf",
    bbox_inches="tight",
)

For raster output:

figure.savefig(
    "figure.png",
    dpi=300,
    bbox_inches="tight",
)

Include in the caption:

• logical or transpiled status,
• backend if transpiled,
• measurement basis,
• shot count or precision,
• mitigation configuration,
• whether data are ideal, modeled, or hardware-derived.

Removed Visualization Patterns

Do not use:

• qiskit.tools.jupyter.QuantumCircuitComposer from old examples,
• pulse schedule drawings based on qiskit.pulse,
• nonexistent plot_state_density helpers,
• V1 quasi-distribution examples presented as Sampler V2 output.

qiskit.pulse was removed in Qiskit 2.0. Use fractional-gate documentation for IBM hardware. Qiskit Dynamics is archived; do not treat it as a maintained replacement for new control-model research.

Troubleshooting

Matplotlib output is unavailable

Install the pinned visualization extra and verify the active interpreter:

uv pip install "qiskit[visualization]==2.5.2"
python -c "import sys, matplotlib; print(sys.executable, matplotlib.__version__)"

Notebook displays nothing

Return the Figure as the final expression or call:

import matplotlib.pyplot as plt

plt.show()

LaTeX drawer fails

Use output="mpl" or output="text" unless a complete TeX toolchain is intentionally installed.

Count labels look reversed

Qiskit prints count strings with the highest-index classical bit on the left. Convert explicitly before mapping characters to qubit-indexed variables.

Backend plot fails

Confirm the object is a compatible BackendV2 and that the visualization extra is installed. Some third-party backends do not provide every field expected by IBM-oriented plotting functions.

Plot is too large

• set fold,
• hide idle wires,
• split logical modules,
• export to SVG,
• include structural metrics in text rather than forcing every instruction into one figure.