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


qiskit.visualization.plot_histogram(data, figsize=(7, 5), color=None, number_to_keep=None, sort='asc', target_string=None, legend=None, bar_labels=True, title=None, ax=None, filename=None)

GitHub(opens in a new tab)

Plot a histogram of input counts data.

Deprecated since version 0.22.0_pending

Using plot_histogram() data argument with QuasiDistribution, ProbDistribution, or a distribution dictionary is pending deprecation as of qiskit-terra 0.22.0. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Instead, use plot_distribution().


  • data (list(opens in a new tab) ordict(opens in a new tab)) – This is either a list of dictionaries or a single dict containing the values to represent (ex {'001': 130})
  • figsize (tuple(opens in a new tab)) – Figure size in inches.
  • color (list(opens in a new tab) orstr(opens in a new tab)) – String or list of strings for histogram bar colors.
  • number_to_keep (int(opens in a new tab)) – The number of terms to plot per dataset. The rest is made into a single bar called ‘rest’. If multiple datasets are given, the number_to_keep applies to each dataset individually, which may result in more bars than number_to_keep + 1. The number_to_keep applies to the total values, rather than the x-axis sort.
  • sort (string) – Could be ‘asc’, ‘desc’, ‘hamming’, ‘value’, or ‘value_desc’. If set to ‘value’ or ‘value_desc’ the x axis will be sorted by the number of counts for each bitstring. Defaults to ‘asc’.
  • target_string (str(opens in a new tab)) – Target string if ‘sort’ is a distance measure.
  • legend (list(opens in a new tab)) – A list of strings to use for labels of the data. The number of entries must match the length of data (if data is a list or 1 if it’s a dict)
  • bar_labels (bool(opens in a new tab)) – Label each bar in histogram with counts value.
  • title (str(opens in a new tab)) – A string to use for the plot title
  • ax (matplotlib.axes.Axes(opens in a new tab)) – 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.
  • filename (str(opens in a new tab)) – file path to save image to.


A figure for the rendered histogram, if the ax kwarg is not set.

Return type




# Plot two counts in the same figure with legends and colors specified.
from qiskit.visualization import plot_histogram
counts1 = {'00': 525, '11': 499}
counts2 = {'00': 511, '11': 514}
legend = ['First execution', 'Second execution']
plot_histogram([counts1, counts2], legend=legend, color=['crimson','midnightblue'],
                title="New Histogram")
# You can sort the bitstrings using different methods.
counts = {'001': 596, '011': 211, '010': 50, '000': 117, '101': 33, '111': 8,
        '100': 6, '110': 3}
# Sort by the counts in descending order
hist1 = plot_histogram(counts, sort='value_desc')
# Sort by the hamming distance (the number of bit flips to change from
# one bitstring to the other) from a target string.
hist2 = plot_histogram(counts, sort='hamming', target_string='001')
Was this page helpful?
Report a bug or request content on GitHub.