Plotly · Function

px.pie

px.pie creates an interactive pie chart from tabular data. It maps numeric values to sector sizes and categories to labels, with options for hover content, naming, and further figure customization.

How it works

px.pie builds a complete Plotly figure from tabular data. Pass a data source plus the column or sequence for sector sizes and another for labels; optional arguments configure grouping, coloring, hover content, text, and layout before the figure is rendered or further updated.

Syntax

plotly.express.pie(data_frame=None, names=None, values=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, category_orders=None, labels=None, color_discrete_sequence=None, color_discrete_map=None, marginal=None, title=None, template=None, width=None, height=None, opacity=None, hole=None, animation_frame=None, animation_group=None, range_color=None, color_continuous_scale=None, color_continuous_midpoint=None, symbol=None, symbol_sequence=None, symbol_map=None, text=None, text_template=None, text_auto=False, groupnorm=None, hover_data=None, **kwargs)

Returns

A Plotly figure object.

Key points

Set values to the numeric data that determines each sector's magnitude.
Set names to the categories shown as sector labels.
Use hover_data to select additional columns for hover display.
Use labels to provide human-friendly display names for columns.
A concise call can combine a dataframe, value column, label column, and chart title.

Common mistakes

Use fig.update_traces for trace-level pie settings such as displayed text; use fig.update_layout for layout changes.

Example: European population by country

import plotly.express as px

df = px.data.gapminder().query("year == 2007 and continent == 'Europe'")
fig = px.pie(df, values="pop", names="country", title="European population")
fig.show()

Creates and displays a pie chart whose sector sizes come from population and labels come from country.

When to use it

Part-to-whole breakdown

Show how a total is divided among named categories.

Geographic or categorical comparison

Display population, sales, or other measures by country or category.

Interactive data exploration

Expose extra fields when users hover over sectors.

Interview questions

QWhat do values and names control?

px.pie creates a pie-chart figure from supplied data. The values argument determines sector sizes, while names supplies sector labels.

Follow-up: How would you change chart details after construction? Use fig.update_traces for trace attributes and fig.update_layout for layout attributes.

QHow is a basic population pie chart constructed?

A typical call passes a dataframe as the first argument, then identifies its population and country columns with values and names. The returned figure can be displayed with fig.show().

Follow-up: How can hover content be customized? Pass hover_data to control which columns appear in the hover information.

QWhat does px.pie return and how is it used?

Plotly Express can create the complete figure in one call, such as px.pie(df, values='pop', names='country', title=...). The figure is then available for rendering or further configuration.

Follow-up: Which related chart types are suitable for hierarchical part-to-whole data? Plotly Express also provides sunburst, treemap, and icicle.

plotly.express.sunburst
plotly.express.treemap
plotly.express.icicle
Figure.update_traces
Figure.update_layout

Source: Pie charts in Python. Checked 2026-10-15.