Plotly · Function

px.density_contour

px.density_contour creates an interactive 2D density-contour plot by binning x/y observations and aggregating each bin. It supports counts by default, or aggregation of a supplied z variable with histfunc.

How it works

px.density_contour groups rows by their x and y coordinates into two-dimensional bins, then computes contour levels from the resulting aggregation. By default it counts rows; supplying z together with histfunc lets the contours represent an aggregation such as an average instead.

Syntax

plotly.express.density_contour(data_frame=None, x=None, y=None, z=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, animation_frame=None, animation_group=None, category_orders=None, labels=None, orientation=None, color_discrete_sequence=None, color_discrete_map=None, marginal_x=None, marginal_y=None, trendline=None, trendline_options=None, trendline_color_override=None, log_x=False, log_y=False, range_x=None, range_y=None, histfunc=None, histnorm=None, nbinsx=None, nbinsy=None, title=None, template=None, width=None, height=None)

Parameters

Name	Type	Description
`data_frame`	`DataFrame or array-like`	Input data, typically a pandas DataFrame, dictionary, or array.
`x`	`str or array-like`	Column or array used for the horizontal coordinate.
`y`	`str or array-like`	Column or array used for the vertical coordinate.
`z`	`str or array-like`	Column or array whose values are aggregated in each bin.
`histfunc`	`str`	Aggregation function applied to z values; counts are used by default when z is absent.
`nbinsx`	`int`	Number of bins along the x dimension.
`nbinsy`	`int`	Number of bins along the y dimension.
`color`	`str or array-like`	Column or array defining discrete color groups.
`facet_col`	`str`	Column used to split the figure into facet panels.

Returns

A Plotly Figure object containing a density-contour trace.

Key points

Call px.density_contour to create an interactive two-dimensional density-contour figure.
The function converts x/y observations into two-dimensional bins before calculating contours.
Bin values come from an aggregation; counting rows is the default, while other aggregations can be selected.
Provide z and histfunc when contour levels should summarize a third variable.
Use facet_col for separate panels and color for discrete grouping within the visualization.
Modify the generated contour trace to fill regions and display contour labels.

Example: Density contour from tabular data

import plotly.express as px

df = px.data.tips()
fig = px.density_contour(df, x="total_bill", y="tip", nbinsx=20, nbinsy=20)
fig.show()

Creates an interactive density-contour figure from the built-in tips dataset, using explicit bin counts for both axes.

When to use it

Reduce over-plotting

Many observations overlap in a scatter plot and obscure structure.

Show aggregated z values

A third numeric field must be summarized spatially across x/y regions.

Compare groups with color and facets

The distribution should be compared across categories or subsets.

Interview questions

QWhat does px.density_contour calculate?

It groups observations into two-dimensional x/y bins and uses the resulting aggregate to draw contour levels. With no z, the default aggregate is a count; with z, histfunc can define an operation such as avg.

Follow-up: How would you visualize dense data without plotting every point? Use a density contour or density heatmap to aggregate overlapping observations into bins.

QWhat input shapes can the function accept?

Pass a dataframe as the first argument and identify the plotted columns with x and y. For wide-form data, the 2D-Cartesian Plotly Express functions, including density_contour, can also accept wide or mixed input.

Follow-up: What dependency is relevant when passing a dictionary or array as data_frame? Plotly Express internally converts it to a pandas DataFrame, so pandas must be installed.

QHow can a density contour represent values other than counts?

Use z to provide values for aggregation and histfunc to choose the aggregation operation. For example, z="sepal_length" with histfunc="avg" makes each bin represent the average z value rather than a row count.

Follow-up: How can the displayed contour appearance be changed after creation? Update the generated trace, for example with fig.update_traces(contours_coloring="fill", contours_showlabels=True).

px.density_heatmap
px.histogram
go.Histogram2dContour

Source: Plotly express arguments in Python. Checked 2026-10-15.