Univariate distribution inspection
Explore the shape and spread of one numeric variable.
Seaborn · Function
histplot
Plot univariate or bivariate histograms that show dataset distributions. histplot supports configurable bins, normalization, grouping, cumulative views, and optional KDE overlays.
How it works
histplot divides one or two variables into bins and displays the observations in those bins. It can condition distributions with hue, choose how values are represented and combined, normalize bin statistics, overlay a kernel-density estimate, and return an axes object for further customization.
Syntax
seaborn.histplot(data=None, *, x=None, y=None, hue=None, weights=None, stat='count', bins='auto', binwidth=None, binrange=None, discrete=None, cumulative=False, common_bins=True, common_norm=True, multiple='layer', element='bars', fill=True, shrink=1, kde=False, kde_kws=None, line_kws=None, thresh=0, pthresh=None, pmax=None, cbar=False, cbar_ax=None, cbar_kws=None, palette=None, hue_order=None, hue_norm=None, color=None, log_scale=None, legend=True, ax=None, **kwargs)Parameters
| Name | Type | Description |
|---|---|---|
data | DataFrame, array, mapping, or sequence | Input data structure or vectors used to populate the plot. |
x | vector or key | Variable assigned to the horizontal axis. |
y | vector or key | Variable assigned to the vertical axis for a bivariate histogram. |
hue | vector or key | Grouping variable used to condition the distributions. |
weights | vector or key | Values used as weights instead of counting every observation equally. |
stat | string | Statistic computed within each bin; the default is count. |
bins | str, int, or array | Bin specification, such as an automatic rule, count, or explicit edges. |
binwidth | number or pair of numbers | Width of each bin. |
binrange | pair of numbers or pairs | Minimum and maximum values used for binning. |
discrete | bool or pair of bools | Whether to treat one or both variables as discrete. |
cumulative | bool | Whether to accumulate bin values. |
common_bins | bool | Whether grouped distributions share bin boundaries. |
Returns
matplotlib.axes.Axes
Key points
- Use histplot for either one-dimensional or two-dimensional distribution views.
- A histogram summarizes observations by assigning them to discrete bins.
- The stat option lets bin heights express more than simple counts.
- Set kde=True to overlay a smoothed density estimate on the histogram.
- Control binning with a bin count or rule, a fixed binwidth, or explicit break locations.
- The hue semantic supports conditional distributions by drawing one histogram per hue value.
Common mistakes
- The bar height is not always a raw count: stat can instead represent frequency, density, or probability mass.
- Using hue creates separate distributions for unique values, so overlapping or stacked groups can change how the comparison reads.
Example: Grouped flipper-length distributions
import seaborn as sns
import matplotlib.pyplot as plt
penguins = sns.load_dataset("penguins")
ax = sns.histplot(
data=penguins,
x="flipper_length_mm",
hue="species",
multiple="layer",
binwidth=3,
)
ax.set_title("Penguin flipper lengths")
plt.show()This draws overlapping, color-coded univariate histograms with three-unit bins.
When to use it
Conditional group comparison
Compare distributions across categories such as species or cohorts.
Bivariate density overview
Display joint concentration for two numeric variables.
Log-scaled distributions
Show long-tailed measurements across multiplicative scales.
Interview questions
QWhat does seaborn.histplot visualize?
histplot is an axes-level function for univariate or bivariate histograms. It partitions values into discrete bins and represents the distribution by the observations assigned to each bin.
Follow-up: How would you make groups comparable when their sample sizes differ? Set an appropriate stat such as density or probability, and choose common bin settings when comparing groups.
QHow do you choose the main variables and grouping variable?
Use x for a univariate histogram and x together with y for a bivariate histogram. The hue semantic can condition the plot on another variable and distinguish the resulting distributions by color.
Follow-up: How can a bivariate histogram show concentration rather than counts? Use a normalized statistic and, where useful, a color mapping or colorbar for the bin values.
QHow can binning be controlled?
The bins argument can specify the number of bins or an explicit binning strategy, while binwidth sets the width directly and binrange limits the range. The function also supports discrete data and cumulative displays.
Follow-up: When is binwidth preferable to an automatic rule? Use it when domain units or consistent bin widths across several plots are more meaningful than a data-dependent choice.
Related
kdeplotdisplotecdfplotrugplotjointplotpairplot