How to Plot a Histogram in Python with Matplotlib (Complete Guide)

Histograms are the fastest way to inspect how values in a dataset are distributed. Before choosing a statistical test, checking for outliers, or deciding whether to log-transform data, a histogram gives you the visual context you need.

Many tutorials stop at plt.hist(data). That is enough for a screenshot, but not enough for technical work where binning choices, scaling, weighting, and reproducibility affect your scientific conclusions. This guide goes from baseline usage to edge cases you will encounter in real data pipelines.

You will get multiple code variants, interpretation guidance, and practical troubleshooting patterns for common failure modes. If your goal is a publication figure or a defensible exploratory analysis, this is the level of histogram control you need.

1. Minimal histogram

Pass your array to ax.hist(). The most important optional argument is bins - an integer sets the number of equal-width bins. For fast exploratory checks, this is fine, but for reporting or comparing cohorts, you should avoid hardcoding a bin count before inspecting spread, outliers, and sample size.

import matplotlib.pyplot as plt
import numpy as np

rng = np.random.default_rng(42)
data = rng.normal(loc=5, scale=1.5, size=300)

fig, ax = plt.subplots(figsize=(7, 4))
ax.hist(data, bins=30, color="#6b21a8", edgecolor="white", linewidth=0.4)
ax.set_xlabel("Value")
ax.set_ylabel("Count")
ax.set_title("Basic Histogram")
plt.tight_layout()

2. Choosing bins with intent

Bin selection controls what structure you can see. Too few bins hide multimodality. Too many bins amplify noise and produce unstable tails. Instead of guessing, compare rule-based options on the same dataset and keep your choice explicit in methods sections.

• Sturges - conservative, good for small near-normal datasets.
• Freedman-Diaconis (fd) - robust to outliers, often strong for skewed experimental data.
• auto - chooses between rules, good as a baseline but still inspect visually.

import matplotlib.pyplot as plt
import numpy as np

rng = np.random.default_rng(42)
data = np.r_[rng.normal(0, 1, 700), rng.normal(4, 0.7, 300)]

fig, axes = plt.subplots(1, 3, figsize=(12, 3.5), sharey=True)
rules = ["sturges", "fd", "auto"]

for ax, rule in zip(axes, rules):
  ax.hist(data, bins=rule, color="#6b21a8", edgecolor="white", linewidth=0.4)
  ax.set_title(f"bins='{rule}'")
  ax.set_xlabel("Value")

axes[0].set_ylabel("Count")
fig.suptitle("How bin rules change your interpretation")
plt.tight_layout()

3. Add a KDE curve on top

Use density=True to normalize the histogram, then overlay a Gaussian KDE for a smooth estimate of the underlying distribution. In reports, describe KDE as a smoothed estimate rather than raw frequency.

import matplotlib.pyplot as plt
import numpy as np
from scipy.stats import gaussian_kde

rng = np.random.default_rng(42)
data = rng.normal(loc=5, scale=1.5, size=300)

fig, ax = plt.subplots(figsize=(7, 4))
ax.hist(data, bins=30, density=True, color="#6b21a8", edgecolor="white",
        linewidth=0.4, alpha=0.6, label="Histogram")

xs = np.linspace(data.min(), data.max(), 200)
kde = gaussian_kde(data)
ax.plot(xs, kde(xs), lw=2, color="#f59e0b", label="KDE")

ax.set_xlabel("Value")
ax.set_ylabel("Density")
ax.legend(frameon=False)
plt.tight_layout()

4. Overlapping histograms for group comparison

When comparing two groups, plot both histograms on the same axes with alpha set below 1. Use density=True if group sizes differ. Counts can be misleading when one cohort has more observations.

import matplotlib.pyplot as plt
import numpy as np

rng = np.random.default_rng(42)
group_a = rng.normal(4, 1.2, 200)
group_b = rng.normal(6, 1.0, 200)

fig, ax = plt.subplots(figsize=(7, 4))
ax.hist(group_a, bins=25, density=True, alpha=0.55, color="#6b21a8", label="Group A")
ax.hist(group_b, bins=25, density=True, alpha=0.55, color="#f59e0b", label="Group B")
ax.set_xlabel("Value")
ax.set_ylabel("Density")
ax.legend(frameon=False)
plt.tight_layout()

5. Weighted histograms for non-uniform sampling

In many workflows, samples do not contribute equally. You may have confidence weights from measurement quality, inverse probability weights in surveys, or replicate-level weighting from merged instruments. Use the weightsargument so your histogram reflects weighted frequency, not raw row count.

import matplotlib.pyplot as plt
import numpy as np

rng = np.random.default_rng(42)
signal = rng.normal(0, 1, 600)

# Simulate acquisition confidence for each sample
weights = np.clip(rng.normal(loc=1.0, scale=0.25, size=signal.size), 0.2, 1.8)

fig, axes = plt.subplots(1, 2, figsize=(11, 4), sharey=True)
axes[0].hist(signal, bins=30, color="#1d4ed8", edgecolor="white", linewidth=0.4)
axes[0].set_title("Unweighted")
axes[0].set_xlabel("Signal")

axes[1].hist(signal, bins=30, weights=weights, color="#b45309", edgecolor="white", linewidth=0.4)
axes[1].set_title("Weighted")
axes[1].set_xlabel("Signal")

axes[0].set_ylabel("Count / weighted count")
plt.tight_layout()

6. Skewed data: log bins and log axes

Particle size, latency, concentration, and many biological intensity datasets are right-skewed. Linear bins over-emphasize the dense left tail and compress the rest. Logarithmic bins plus a log x-axis often produce a more interpretable shape. Keep in mind that bin widths are no longer equal in linear space, so report this explicitly in figure captions.

import matplotlib.pyplot as plt
import numpy as np

rng = np.random.default_rng(42)
data = rng.lognormal(mean=1.6, sigma=0.9, size=1500)

# Build logarithmic bin edges
log_bins = np.logspace(np.log10(data.min()), np.log10(data.max()), 40)

fig, axes = plt.subplots(1, 2, figsize=(12, 4))
axes[0].hist(data, bins=40, color="#6b21a8", edgecolor="white", linewidth=0.4)
axes[0].set_title("Linear bins")
axes[0].set_xlabel("Value")
axes[0].set_ylabel("Count")

axes[1].hist(data, bins=log_bins, color="#6b21a8", edgecolor="white", linewidth=0.4)
axes[1].set_xscale("log")
axes[1].set_title("Log bins + log x-axis")
axes[1].set_xlabel("Value (log scale)")

plt.tight_layout()

7. Matplotlib vs Seaborn vs Plotly for histograms

The best library depends on your output target. Matplotlib offers maximum control for journal exports. Seaborn accelerates statistical defaults. Plotly gives interactivity for dashboards and exploratory notebooks.

Quick reference: key parameters

8. Common mistakes and robust fixes

Histogram bugs are often data quality bugs in disguise. Before styling, validate numeric types, remove non-finite values, and lock your bin strategy. If your figure changes drastically across reruns, inspect random seeds and preprocessing order.

• Too few bins - large bins hide bimodality or skewness. Use bins="auto" as a starting point.
• Comparing raw counts - if sample sizes differ, normalise with density=True before overlapping.
• No axis label - always label both axes, including the units on the x-axis.
• Missing caption - state the number of observations (n) in the figure caption or on the plot.
• Ignoring NaN or inf values - clean arrays before plotting or you will get unstable bins and hard-to-debug behavior.
• Changing bins between cohorts - when comparing groups, use a shared bin edge definition.

import matplotlib.pyplot as plt
import numpy as np

def clean_numeric(series):
  arr = np.asarray(series, dtype=float)
  arr = arr[np.isfinite(arr)]
  if arr.size == 0:
    raise ValueError("No finite numeric values available for histogram")
  return arr

raw = [1.1, 2.0, np.nan, np.inf, 3.4, 4.1, -np.inf, 2.8]
data = clean_numeric(raw)

fig, ax = plt.subplots(figsize=(6, 4))
ax.hist(data, bins="auto", color="#6b21a8", edgecolor="white", linewidth=0.4)
ax.set_xlabel("Value")
ax.set_ylabel("Count")
ax.set_title("Histogram after numeric cleaning")
plt.tight_layout()

9. Publication-ready histogram checklist

1. Report sample size (n) in caption or panel text.
2. Declare bin rule or fixed bin width explicitly.
3. Use consistent bins across compared cohorts.
4. Label x-axis units and whether y-axis is count or density.
5. Document preprocessing: outlier handling, filtering, and transforms.
6. Export at target journal dimensions and verify readability at print scale.

10. When to use a histogram vs alternatives

Histograms are excellent for showing distribution shape, but they are not always the best final figure. If your audience needs quartiles and outlier emphasis, a box plot may communicate faster. If you need full density shape comparison with small samples, violin plots can be more stable than aggressively binned histograms.

A practical workflow is: start with histogram for quick distribution diagnostics, validate assumptions, then choose the final chart form based on the message you need to communicate in the paper or report.

11. Advanced edge cases you should handle explicitly

Technical datasets rarely follow clean textbook assumptions. If you are working with sensor streams, assay readouts, or merged multi-site data, your histogram pipeline should include edge-case handling as first-class logic. Treat these as part of the analysis method, not cosmetic cleanup.

• Zero-inflated distributions - many biological and reliability datasets include a large spike at zero plus a continuous positive tail. Consider plotting a dedicated zero bar annotation and a second panel for non-zero values to avoid flattening useful variation.
• Censored measurements - if values below detection limit are imputed, your left tail may be artificial. Mark detection thresholds with vertical reference lines and mention censoring rules in captions.
• Integer count data - for low-range count variables (for example read counts or defect counts), use bin edges aligned to integer boundaries. Arbitrary fractional bins can imply precision that does not exist in the measured variable.
• Streaming windows - in online QC systems, histograms computed on rolling windows can drift due to changing sample volume. Keep a fixed bin edge policy and version your windowing settings for reproducible audits.
• Mixture populations - multimodal peaks may represent true subpopulations rather than noise. Before smoothing them away, verify whether modality aligns with treatment group, batch, instrument, or site.

12. Interpreting histogram shapes without overclaiming

Histogram interpretation is useful but easy to overstate. Shape alone does not prove mechanism. Use the plot to generate hypotheses, then test them with domain checks and formal statistics.

13. Domain-specific implementation notes

The same plotting function behaves differently across domains because data collection constraints differ. These patterns reduce avoidable review comments in technical papers and internal reports.

• Clinical measurements - always annotate units and detection limits. If subgroup sample sizes differ strongly, favor density-normalized overlays plus subgroup-specific sample counts.
• Materials characterization - grain size and particle distributions are typically right-skewed. Use log bins and report the exact edge definition so another lab can reproduce your visual summary.
• A/B experimentation - compare control and treatment with shared bins and explicit cohort sizes. Pair histograms with confidence intervals or bootstrap summaries to avoid visual-only conclusions.
• Sensor engineering - if calibration changes over time, stratify histograms by calibration era. Mixed-calibration histograms can create false multimodality and mislead threshold setting.

14. Common error messages and immediate fixes

If you are building production notebooks or reusable plotting utilities, add guards for these failure cases. Most histogram runtime issues come from invalid data arrays rather than plotting API syntax.

• ValueError: autodetected range of [nan, nan] is not finite- clean non-finite values before binning.
• TypeError with mixed string and numeric arrays- cast to numeric explicitly and log rejected rows.
• Unreadable overlapping fills- lower alpha and use step histograms or faceting.
• Histogram shape changes between runs- control random seed, filtering order, and bin-edge policy.
• Axis labels clipped in export- apply plt.tight_layout() and verify target figure size before saving.

15. FAQ for technical teams