Plotly · Function

update_layout

Updates a Plotly figure's layout from a dictionary, keyword arguments, or both. Updates are recursive by default and the Figure object is returned.

How it works

Call update_layout on a Figure to change layout properties using either a dictionary, keyword arguments, or both. Nested dictionaries are merged recursively by default; set overwrite=True when the supplied values should replace existing nested properties.

Syntax

Figure.update_layout(dict1=None, overwrite=False, **kwargs) → plotly.graph_objects._figure.Figure

Parameters

Name	Type	Description
`dict1`	`dict, optional`	Dictionary of layout properties to update.
`overwrite`	`bool, optional`	If True, overwrite existing properties; otherwise apply recursive updates while preserving unspecified properties.
`kwargs`	`keyword arguments`	Keyword/value pairs of layout properties to update.

Returns

The Figure object that update_layout was called on; return type BaseFigure.

Key points

Use a mapping, keyword arguments, or both to specify layout changes.
Nested layout values are merged into the existing layout rather than rebuilding the whole layout by default.
Set overwrite=True when the incoming layout should replace existing properties.
The method returns the Figure instance on which it was invoked.
Keyword arguments represent individual layout property/value updates.

Common mistakes

The default recursive behavior preserves unspecified nested layout properties; use overwrite=True only when replacement is intended.

Example: Update a figure layout

import plotly.express as px

fig = px.scatter(x=[1, 2, 3], y=[3, 1, 2])
fig.update_layout(
    title="Sample chart",
    width=600,
    height=400,
    margin=dict(l=40, r=20, t=60, b=40),
)
fig.show()

Creates a scatter figure, then changes several layout properties with keyword arguments and a nested margin dictionary.

When to use it

Set titles, dimensions, colors, fonts, margins, and legend placement.

Chart styling

Apply a shared dictionary of layout settings to multiple figures.

Reusable configuration

Modify selected nested properties while retaining unrelated existing layout values.

Incremental customization

Interview questions

QWhat does Figure.update_layout do, and what does it return?

update_layout changes a figure's layout using a dictionary, keyword arguments, or both. It returns the same Figure object, so calls can be chained or followed by other figure operations.

Follow-up: How can nested properties be replaced rather than merged? Pass overwrite=True to replace existing properties instead of recursively applying the update.

QHow are nested layout dictionaries handled by default?

The method recursively updates the existing layout structure by default. For example, supplying margin=dict(t=60) changes the top margin while preserving other existing margin values.

Follow-up: What happens if overwrite=True is supplied? Existing nested properties are overwritten by the supplied update rather than preserved when omitted.

QWhat inputs can update_layout accept?

The signature accepts dict1=None, overwrite=False, and arbitrary keyword arguments. dict1 contains properties to update, while kwargs provide property/value pairs such as title or width.

Follow-up: Can the dictionary and keyword forms be combined? Yes; both are accepted in the same call and contribute to the layout update.

Figure.update_traces
Figure.update_layout_images
Figure.update_annotations
plotly.graph_objects.Layout

Source: plotly.graph_objects.Figure.update_layout. Checked 2026-10-15.