Plotly · Function

px.sunburst

px.sunburst creates interactive sunburst charts for hierarchical data. Define the hierarchy with path columns or explicit ids and parents, and optionally control sector size and color.

How it works

Call px.sunburst with tabular data and either path columns or explicit ids and parents. The path form derives the hierarchy from successive columns; values controls sector sizing, while color can encode an additional measure. The function returns a Plotly Figure that can be displayed or further customized.

Syntax

plotly.express.sunburst(data_frame=None, names=None, values=None, parents=None, ids=None, path=None, color=None, color_continuous_scale=None, range_color=None, color_continuous_midpoint=None, color_discrete_sequence=None, color_discrete_map=None, hover_name=None, hover_data=None, custom_data=None, labels=None, title=None, template=None, width=None, height=None, maxdepth=None, branchvalues=None, color_discrete_map=None, **kwargs)

Parameters

Name	Type	Description
`data_frame`	`DataFrame or array-like`	Input data, commonly a pandas DataFrame.
`path`	`list of str or columns`	Columns defining successive hierarchy levels.
`values`	`str, int, Series, or array-like`	Column or array supplying sector sizes.
`color`	`str, int, Series, or array-like`	Column or array used to determine colors.
`ids`	`str, int, Series, or array-like`	Explicit node identifiers; use instead of path.
`parents`	`str, int, Series, or array-like`	Explicit parent identifiers; use instead of path.

Returns

A plotly.graph_objects.Figure object.

Key points

The chart displays a hierarchy as concentric sectors extending from a root node toward leaf nodes.
Rows in the input DataFrame contribute sectors to the generated visualization.
Use path with an ordered list of columns to define hierarchy levels.
In an explicit parent-based hierarchy, assign the root an empty-string parent.
Numeric node colors aggregate child colors using the children’s values as weights.

Common mistakes

Do not combine path with id or parent; choose either the column-based hierarchy or the explicit parent-child representation.
For uneven hierarchy rows, represent absent levels with None so the hierarchy remains valid.

Example: Build a sunburst from hierarchical columns

import plotly.express as px

df = px.data.tips()
fig = px.sunburst(df, path=['day', 'time', 'sex'], values='total_bill')
fig.show()

Creates a sunburst from the tips dataset, using three columns as hierarchy levels and total_bill to size sectors.

When to use it

Hierarchical category exploration

Explore nested categories, such as continent, country, and region.

Part-to-whole analysis

Show how a quantitative total is distributed across parent and child nodes.

Multi-level DataFrame visualization

Inspect multiple dimensions of a rectangular DataFrame.

Interview questions

QHow does px.sunburst represent hierarchical tabular data?

Use path when each hierarchy level is stored in its own DataFrame column. Each row contributes to the resulting sunburst hierarchy, and values can determine sector size.

Follow-up: When would explicit ids and parents be preferable? They are useful when the hierarchy is already represented as node identifiers and parent relationships rather than rectangular level columns.

QHow is a root node represented with explicit parents?

The parents representation assigns each sector a parent; the root uses an empty string as its parent. This directly describes the tree structure.

Follow-up: What constraint applies when path is supplied? id and parent should not also be provided.

QHow does numeric color aggregation work?

A color argument adds a measure or category used for node coloring. For a numeric measure, a node’s color is computed from its children using a value-weighted average.

Follow-up: What determines the weighting? The child sectors’ values provide the weights, so the aggregation reflects their sizes.

plotly.express.treemap
plotly.express.icicle
plotly.graph_objects.Sunburst

Source: Sunburst Charts in Python. Checked 2026-10-15.