Seaborn Boxplot: sns.boxplot Syntax, Parameters and How to Read It

A seaborn boxplot is drawn with seaborn.boxplot(): pass a DataFrame as data, name the numeric column on one axis and the grouping column on the other, and seaborn draws one box per group showing the median, the quartile box, the whiskers and any outlying points. This guide follows the current seaborn documentation (v0.13.2), explains exactly what the whiskers mean, and separates the options that belong to seaborn from those passed through to matplotlib.

What a seaborn boxplot is used for in research

A boxplot summarises the distribution of a numeric variable and lets you compare that distribution across groups, such as a measurement across treatment arms or a score across site categories. It is a common first look at spread, skew and outliers before a formal test. For the general logic of reading box plots in any software, see box-and-whisker plots compared across tools; for how skew shows up in the box, see reading a right-skewed box plot. If you want to see the full shape of each distribution rather than five summary values, seaborn violin plots are the usual alternative.

Install or access seaborn

Seaborn’s installation page lists these commands:

• pip install seaborn
• pip install seaborn[stats] (adds the optional statistical dependencies)
• conda install seaborn
• conda install seaborn -c conda-forge

Per the installation page, seaborn requires Python 3.8 or later and the packages numpy, pandas and matplotlib. Optional packages are statsmodels, scipy and fastcluster. The page also notes that the main Anaconda repository can be slow to add new releases, which is why the conda-forge channel is listed separately. Because the plot is built on matplotlib, see seaborn vs matplotlib if you are deciding which to use for a figure.

Step-by-step: draw a grouped boxplot

The examples below use the Titanic dataset that ships with seaborn’s example data, exactly as in the official function reference.

1. Import the library and load a DataFrame: import seaborn as sns, then titanic = sns.load_dataset("titanic").
2. Draw one box per group: sns.boxplot(data=titanic, x="class", y="age", hue="alive"). Here x is the grouping column, y the numeric column, and hue splits each group into a second set of boxes.
3. For unfilled boxes with a small gap between the hue levels (v0.13.0 and later): sns.boxplot(data=titanic, x="class", y="age", hue="alive", fill=False, gap=.1).
4. For a horizontal plot with whiskers covering the full range of the data: sns.boxplot(data=titanic, x="age", y="deck", whis=(0, 100)).
5. To place boxes at their numeric positions on a continuous axis: ax = sns.boxplot(x=titanic["age"].round(-1), y=titanic["fare"], native_scale=True).

Key parameters and defaults

The documented signature is seaborn.boxplot(data=None, *, x=None, y=None, hue=None, order=None, hue_order=None, orient=None, color=None, palette=None, saturation=0.75, fill=True, dodge='auto', width=0.8, gap=0, whis=1.5, linecolor='auto', linewidth=None, fliersize=None, hue_norm=None, native_scale=False, log_scale=None, formatter=None, legend='auto', ax=None, **kwargs).

• order and hue_order set the order in which categories are drawn.
• orient accepts "v" or "h"; as of v0.13.0 it also accepts "x" or "y".
• dodge='auto' is the default as of v0.13.0.
• fill, gap, linecolor, native_scale, log_scale, formatter and legend are new in v0.13.0; hue_norm is new in v0.12.0. Code copied from older tutorials may not use them, and running it on an older seaborn will fail.
• palette sets the colours; see seaborn color palettes.

What do the whiskers show?

With the default whis=1.5, each whisker extends to the farthest data point that lies within 1.5 times the interquartile range (IQR) of the nearest hinge (the edge of the box). Points beyond the whiskers are drawn individually as outliers. Matplotlib’s documentation states that this default corresponds to Tukey’s original definition of boxplots.

If you pass a pair of numbers instead, they are read as percentiles: whis=(0, 100) places the whiskers at the minimum and maximum, so no points are flagged as outliers. Matplotlib’s own example of a percentile pair is (5, 95). Whichever rule you use, state it in the figure legend or methods text, because a reader cannot tell a 1.5 × IQR whisker from a percentile whisker by looking at the picture.

Output and how to read it

• The line inside each box is the median.
• The box spans the first to third quartile, so its height is the IQR.
• The whiskers follow the whis rule above.
• Individual points past the whiskers are outliers under that rule. They are a flag for inspection, not an instruction to delete data.
• With hue, boxes at the same position on the grouping axis are the hue levels of one group.

Which parameters belong to matplotlib?

showfliers, notch and showcaps are not named seaborn parameters. They go through **kwargs to matplotlib’s Axes.boxplot, and seaborn’s own reference page uses notch and showcaps in an example. Matplotlib documents these defaults: showfliers=True (show the outliers beyond the caps), notch=False (notches, when turned on, represent the confidence interval around the median) and showmeans=False. So sns.boxplot(data=titanic, x="class", y="age", showfliers=False) hides the outlier points through matplotlib, and the same call with notch=True draws notched boxes.

Troubleshooting

The boxes run the wrong way

If both axes are numeric or both are categorical, seaborn has to guess the direction. Set orient explicitly, using "v" or "h" (or "x" or "y" in v0.13.0 and later).

A numeric x variable is drawn as evenly spaced categories

By default the x values are treated as categories. Set native_scale=True, as in the fourth official example, to place the boxes at their numeric positions.

Colours look paler than the palette

saturation defaults to 0.75, which desaturates the colours. Set saturation=1 to use the palette colours as specified.

Hue boxes overlap or sit apart

The dodge parameter controls whether hue levels are drawn side by side (default 'auto' as of v0.13.0), and gap adds space between them.

An argument is rejected or has no effect

Check the seaborn version with seaborn.__version__. Parameters introduced in v0.13.0 (such as fill and gap) do not exist in earlier releases.

Free alternatives

Option	What it gives you	Source
seaborn boxplot	Grouped boxes from a DataFrame, with hue, fill, gap and native_scale	seaborn.pydata.org, v0.13.2
matplotlib Axes.boxplot	The underlying function; whis, showfliers, notch and showmeans are its own arguments	matplotlib.org, stable docs
seaborn violin plot	Shows the distribution shape instead of five summary values	CASRAI guide

For a wider workflow around these plots, see Python for exploratory data analysis.

FAQ

What is the default whisker length in a seaborn boxplot?

1.5 times the interquartile range, set by whis=1.5. Whiskers end at the farthest data point within that distance of the box; points beyond are outliers.

How do I show every data point, with no outliers flagged?

Set whis=(0, 100) so the whiskers span the full range, as in the official example.

How do I hide outliers or add notches?

Pass showfliers=False or notch=True. These are forwarded to matplotlib’s Axes.boxplot rather than being seaborn parameters.

Why does my tutorial’s code fail?

Many tutorials predate v0.13.0. Check which parameters the code uses against the version you have installed.

Sources

• seaborn.boxplot reference, v0.13.2: https://seaborn.pydata.org/generated/seaborn.boxplot.html (checked 2026-10-29)
• seaborn installation: https://seaborn.pydata.org/installing.html (checked 2026-10-29)
• matplotlib.axes.Axes.boxplot: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html (checked 2026-10-29)