Plotly · Module

fig.add_trace

Adds one trace to a Plotly graph-object figure and returns the modified figure. It also supports selecting a subplot and, where configured, its secondary y-axis.

How it works

fig.add_trace accepts a graph-object trace or a trace dictionary, appends it to the figure, and returns the figure so calls can be chained. For subplot figures, row, col, and secondary_y select the destination axis.

Syntax

fig.add_trace(trace, row=None, col=None, secondary_y=None, exclude_empty_subplots=False)

Parameters

Name	Type	Description
`trace`	`BaseTraceType or dict`	Trace object or dictionary to add. A trace object may be a graph-object instance such as Scatter or Bar; a dictionary specifies a trace type and its properties.
`row`	`int or 'all' or None`	Subplot row index, starting at 1; valid for figures created with make_subplots.
`col`	`int or 'all' or None`	Subplot column index, starting at 1; valid for figures created with make_subplots.
`secondary_y`	`bool or None`	Whether to add the trace to the secondary y-axis of the selected subplot.
`exclude_empty_subplots`	`bool`	If true, prevents adding the trace to subplots that do not already contain traces.

Returns

The modified plotly.graph_objects.Figure.

Key points

Use add_trace to append a new data series to an existing graph-object figure.
The input is typically a concrete trace object such as go.Scatter or go.Bar.
An empty Figure can be built incrementally by adding traces one after another.
For subplot layouts, row and col identify the target subplot.
add_trace differs from append_trace because it returns the modified figure.

Common mistakes

The row and col options apply only to figures created with Plotly's subplot-building utility.
A dictionary without a type field is interpreted as a scatter trace, which may be unintended.
Do not substitute append_trace when chaining is required; unlike add_trace, it does not return the figure.

Example: Add a scatter trace

import plotly.graph_objects as go

fig = go.Figure()
fig.add_trace(go.Scatter(x=[1, 2, 3], y=[2, 1, 2], mode="lines+markers"))
fig.show()

Creates a figure, adds a scatter trace, and displays the resulting interactive chart.

When to use it

Append series to an empty figure

Building a chart incrementally

Place traces in selected subplots

Composing dashboards

Add trace objects or dictionaries

Programmatic chart generation

Interview questions

QWhat does Figure.add_trace do, and what can trace be?

It adds one graph-object trace to a figure and returns the figure. The trace can be a graph-objects instance such as Scatter or Bar, or a dictionary describing the trace.

Follow-up: How would you target a subplot? Pass row and col to add_trace; secondary_y can select the secondary y-axis when the subplot supports it.

QHow do you add a trace to a particular subplot?

Use row and col, with indexes beginning at 1, to place the trace in a chosen subplot. These arguments are meaningful for figures created with make_subplots.

Follow-up: What happens if the figure is not a subplot figure? The subplot-position arguments are not valid for that figure configuration.

QHow are dictionary traces interpreted?

A trace dictionary uses its type property to select the trace class, and its remaining properties become constructor arguments. If type is absent, Plotly assumes scatter.

Follow-up: When predictable trace construction matters, provide an explicit type or use a graph-object class such as go.Bar.

Figure.add_traces
Figure.add_scatter
Figure.add_bar
plotly.subplots.make_subplots

Source: plotly.graph_objects.Figure — 7.0.0 documentation. Checked 2026-10-15.