Plotly · Function

make_subplots

Creates a Plotly Figure with a configurable grid of subplots. It supports shared axes, titles, spacing, relative dimensions, specialized subplot types, and per-cell configuration.

How it works

Call make_subplots to create a Figure whose layout contains a configured subplot grid. Then add traces by specifying their row and column; options such as shared axes, titles, spacing, dimensions, and per-cell specs control the grid.

Syntax

plotly.subplots.make_subplots(rows=1, cols=1, shared_xaxes=False, shared_yaxes=False, start_cell='top-left', print_grid=False, horizontal_spacing=None, vertical_spacing=None, subplot_titles=None, column_widths=None, row_heights=None, specs=None, insets=None, column_titles=None, row_titles=None, x_title=None, y_title=None, figure=None, **kwargs)

Parameters

Name	Type	Description
`rows`	`int`	Number of rows in the subplot grid; default 1 and must be greater than zero.
`cols`	`int`	Number of columns in the subplot grid; default 1.
`shared_xaxes`	`bool`	Whether x axes are shared across subplots; default False.
`shared_yaxes`	`bool`	Whether y axes are shared across subplots; default False.
`start_cell`	`str`	Grid origin direction; default 'top-left'.
`print_grid`	`bool`	Whether to print a representation of the subplot grid; default False.
`horizontal_spacing`	`float`	Spacing between columns in normalized plot coordinates.
`vertical_spacing`	`float`	Spacing between rows in normalized plot coordinates.
`subplot_titles`	`tuple/list`	Titles to position as annotations for subplots.
`column_widths`	`list`	Relative widths of subplot columns.
`row_heights`	`list`	Relative heights of subplot rows.
`specs`	`list[list[dict\|None]]`	Per-cell subplot configuration, including type and spanning options.

Returns

plotly.graph_objects.Figure with predefined subplots configured in layout.

Key points

The function constructs and returns a Figure whose layout is already configured for the requested subplot arrangement.
rows controls how many horizontal grid rows are created.
cols controls how many vertical grid columns are created.
horizontal_spacing controls the gap between neighboring columns using normalized plot coordinates.
subplot_titles creates text annotations positioned as titles for the individual subplot cells.
The specs matrix can select specialized subplot types for cells, including polar, geographic, and parallel-coordinate plots.

Common mistakes

The rows argument must be a positive integer; zero or negative row counts are invalid.
horizontal_spacing is normalized, so its value must stay within the inclusive range from 0 to 1.

Example: Create a two-panel figure

from plotly.subplots import make_subplots
import plotly.graph_objects as go

fig = make_subplots(
    rows=1,
    cols=2,
    subplot_titles=("Sales", "Trend"),
    shared_yaxes=True,
)
fig.add_trace(go.Bar(x=["A", "B"], y=[10, 15]), row=1, col=1)
fig.add_trace(go.Scatter(x=["A", "B"], y=[10, 15], mode="lines+markers"), row=1, col=2)
fig.show()

Creates a one-row, two-column figure, adds one trace to each cell, and displays the result.

When to use it

Side-by-side or stacked comparisons

Comparing related charts in one figure

Mixed subplot types

Combining chart families

Shared-axis dashboards

Aligning related measurements

Custom spacing and proportions

Controlling panel geometry

Interview questions

QWhat does make_subplots return, and how are traces placed?

make_subplots returns a plotly.graph_objects.Figure with a predefined subplot layout. Traces can then be assigned to individual cells using row and col when calling figure methods such as add_trace.

Follow-up: How would you create a mixed subplot grid? Pass a specs matrix, using each cell's type option to select subplot types such as scattergeo or surface.

QHow do you configure shared axes and subplot titles?

Set rows and cols to define the grid, then use shared_xaxes or shared_yaxes to link axes across appropriate subplots. subplot_titles can add title annotations for the cells.

Follow-up: How can one cell use a secondary y-axis? Provide a cell specification containing secondary_y: True, then add the relevant trace with secondary_y=True.

QHow do you customize different cells in a subplot grid?

Use specs for per-cell configuration, including subplot type and spanning behavior; None leaves a grid cell uninitialized. column_widths and row_heights control relative sizing, while horizontal_spacing and vertical_spacing control gaps.

Follow-up: How do you span multiple grid cells? Set colspan or rowspan in the starting cell's specification and place None in cells occupied by that spanning subplot.

plotly.subplots
plotly.graph_objects.Figure.add_trace
plotly.graph_objects.Figure.set_subplots
plotly.graph_objects.Figure.update_xaxes
plotly.graph_objects.Figure.update_yaxes

Source: plotly.subplots : helper function for laying out multi-plot figures. Checked 2026-10-15.