Plotly · Function

px.box

Creates interactive box-and-whisker plots from tabular or array-like data. It supports grouping, facets, colors, point overlays, notches, logarithmic axes, and other figure styling options.

How it works

px.box groups rows from a data frame into box-and-whisker marks that show distribution. The box spans Q1–Q3, Q2 appears as an internal line, and default whiskers extend 1.5 IQR beyond the quartiles; grouping, faceting, orientation, point display, and styling are configurable.

Syntax

plotly.express.box(data_frame=None, x=None, y=None, color=None, facet_row=None, facet_col=None, facet_col_wrap=0, facet_row_spacing=None, facet_col_spacing=None, hover_name=None, hover_data=None, custom_data=None, animation_frame=None, animation_group=None, category_orders=None, labels=None, color_discrete_sequence=None, color_discrete_map=None, orientation=None, boxmode=None, log_x=False, log_y=False, range_x=None, range_y=None, points=None, notched=False, title=None, subtitle=None, template=None, width=None, height=None) → plotly.graph_objects._figure.Figure

Parameters

Name	Type	Description
`data_frame`	`DataFrame \| array-like \| dict`	Data frame, array-like object, or dictionary supplying data and column names.
`x`	`str \| int \| Series \| array-like`	Column name, index, Series, or array-like values for the horizontal dimension or grouping.
`y`	`str \| int \| Series \| array-like`	Column name, index, Series, array-like values, or a list of columns for the vertical distribution.
`color`	`str \| int \| Series \| array-like`	Column or values used to assign colors to groups.
`facet_row`	`str \| int \| Series \| array-like`	Column or values used to create row facets.
`facet_col`	`str \| int \| Series \| array-like`	Column or values used to create column facets.
`facet_col_wrap`	`int`	Number of facet columns before wrapping.
`facet_row_spacing`	`float`	Spacing between facet rows.
`facet_col_spacing`	`float`	Spacing between facet columns.
`hover_name`	`str \| int \| Series \| array-like`	Column or values used as the hover label.
`hover_data`	`list \| dict`	Additional data shown in hover labels.
`custom_data`	`list \| dict`	Additional custom data attached to traces.

Returns

plotly.graph_objects._figure.Figure

Key points

Use px.box to summarize a variable’s distribution through quartiles rather than showing only individual values.
The rectangle represents the interquartile range, from the first to the third quartile.
The median is drawn as a line inside each box.
Set x to a categorical column to create separate distributions for each category.
The function is a high-level interface suitable for quickly generating and styling complete figures.

Common mistakes

Default whiskers use 1.5 times the interquartile range beyond the box edges; do not assume they always represent the minimum and maximum.
Underlying observations are not all shown by default: points defaults to outliers, and can be changed to all or False.

Example: Grouped box plot

import plotly.express as px

fig = px.box(
    px.data.tips(),
    x="day",
    y="total_bill",
    color="smoker",
    points="all",
    notched=True,
)
fig.show()

Creates grouped, colored box plots of restaurant bills, displaying every underlying observation and notches.

When to use it

Category distribution comparison

Compare a numeric measurement across categories such as days, groups, or conditions.

Distribution and outlier analysis

Inspect the spread and possible outliers of a variable.

Multi-column distribution views

Compare several numeric columns in wide-form or mixed-form data.

Multidimensional exploratory analysis

Show subgroup differences with color, facets, or animation.

Interview questions

QWhat does px.box produce and what do its boxes represent?

px.box returns a Plotly Figure. It groups data-frame rows into box-and-whisker marks; each box covers Q1 through Q3 and the median is shown inside it.

Follow-up: How are the default whiskers determined? They extend from the box edges by 1.5 times the IQR, where IQR is Q3 minus Q1.

QHow do x and y control grouping and values?

Pass a column name through x to create a box for each value of that column, while y supplies the distribution being plotted. For example, x="time" and y="total_bill" creates groups by time.

Follow-up: How can multiple numeric columns be plotted? Use wide-form input by supplying a list of column names for y.

QHow do you control the points displayed over a box plot?

The points argument controls raw observations: "all" displays every point, "outliers" displays only outliers, and False hides them. The default is outliers.

Follow-up: What does notched=True change? It requests notched boxes, which provide a visual indication related to uncertainty around the median.

plotly.express.violin
plotly.express.strip
plotly.express.histogram
plotly.graph_objects.Figure

Source: plotly.express.box — 7.1.0 documentation. Checked 2026-10-15.