Plotly · Module

fig.to_json

Figure.to_json() converts a Plotly figure to a JSON string. It supports validation, readable formatting, UID removal, and selectable JSON encoding engines.

How it works

Call Figure.to_json() to serialize a Plotly figure into JSON text. Validation is enabled by default, output can be formatted for readability, trace UIDs are omitted by default, and the encoder can be selected explicitly or left to Plotly's configured default.

Syntax

fig.to_json(validate=True, pretty=False, remove_uids=True, engine=None)

Parameters

Name	Type	Description
`fig`	`Figure or dict`	Figure object or dict representing a figure.
`validate`	`bool`	Whether to validate the figure before conversion. Defaults to `True`.
`pretty`	`bool`	Whether to pretty-print the JSON. Defaults to `False`.
`remove_uids`	`bool`	Whether to omit trace UIDs. Defaults to `True`.
`engine`	`str or None`	JSON encoding engine: `json`, `orjson`, or `auto`; defaults to Plotly's configured engine.

Returns

Representation of figure as a JSON string

Key points

The method serializes a Plotly figure into JSON text.
With validate=True, Plotly validates the figure before serialization; set it to False to skip validation.
pretty controls whether the returned JSON is formatted for readability or kept compact.
remove_uids controls whether trace UID fields are excluded from the serialized output.
Use engine to choose the encoder, including the built-in json, optional orjson, or automatic selection.
The return value is the figure's JSON representation as a string.

Common mistakes

Trace UIDs are omitted by default; set remove_uids=False when those identifiers must be preserved.
Selecting the orjson engine requires the optional orjson package to be installed.

Example: Serialize a figure to JSON

import plotly.graph_objects as go

fig = go.Figure(data=go.Bar(y=[2, 1, 3]))
json_text = fig.to_json(pretty=True)
print(json_text)

Creates a bar figure, serializes it to formatted JSON text, and prints the result.

When to use it

Save figure configuration

Persist a chart definition as text for storage or later reconstruction.

Debug figure serialization

Inspect the complete serialized structure while debugging chart properties.

Exchange chart data

Send a chart specification to a consumer that expects JSON.

Interview questions

QWhat does Figure.to_json() return, and what are its main defaults?

It returns a JSON string representation of the figure. The input figure is validated by default before conversion, and pretty=True produces human-readable formatting.

Follow-up: How would you preserve trace identifiers? Pass remove_uids=False, because the default omits them.

QWhat is the purpose of the pretty parameter?

pretty=False requests the most compact representation, while pretty=True pretty-prints the JSON. This controls formatting rather than the figure's plotted content.

Follow-up: Which option should be used for compact storage or transmission? Leave pretty at its default False.

QHow can JSON encoding be selected?

The engine parameter selects the JSON encoder: json, orjson, or auto. If omitted, Plotly uses the current default engine configured in plotly.io.json.config.default_engine.

Follow-up: What does auto do? It uses orjson when available and otherwise falls back to json.

plotly.io.from_json
plotly.io.to_json_plotly
plotly.io.write_json
Figure.to_plotly_json

Source: plotly.io.to_json — 5.23.0 documentation. Checked 2026-10-15.