Plotly · Module

graph_objects

plotly.graph_objects is Plotly’s low-level Python interface for constructing figures from traces, layouts, and related graph-object classes. Its Figure objects support validation, manipulation, rendering, and serialization.

How it works

The module provides automatically generated Python classes for the non-leaf parts of Plotly’s figure schema, including Figure, Layout, and trace types. Construct or update these objects, access properties with attributes or keys, and render or serialize the resulting figure.

Syntax

import plotly.graph_objects as go

Parameters

Name	Type	Description
`data`	`list\|tuple\|trace`	Trace specifications, supplied as a list, tuple, or single trace instance.
`layout`	`Layout\|dict`	Layout specification passed to the Layout constructor.
`frames`	`list\|tuple`	Animation-frame specifications.
`skip_invalid`	`bool`	Whether invalid properties are silently skipped.

Returns

A hierarchy of graph-object instances representing a Plotly figure; rendering and serialization are provided by Figure methods.

Key points

The module’s generated class hierarchy models Plotly’s figure schema.
Figure and FigureWidget represent complete figures; FigureWidget is compatible with ipywidgets.
The module includes trace classes such as Scatter and Bar plus the Layout class.
Many convenience methods, including update_layout() and add_trace(), accept magic-underscore property notation.
Figure data structures are serialized to JSON before Plotly.js renders them.
Graph objects validate figure properties against the supported schema.

Common mistakes

Plotly Express is the recommended high-level entry point; use graph_objects when you need lower-level figure construction or precise control.
Graph-object properties support both dictionary-style access such as fig["layout"] and attribute-style access such as fig.layout.

Example: Build and render a bar chart

import plotly.graph_objects as go

fig = go.Figure(
    data=[go.Bar(x=["A", "B", "C"], y=[2, 5, 3])],
    layout=go.Layout(title="Example")
)
fig.show()

Creates a Figure from a graph-object trace and layout, then renders it.

When to use it

Fine-grained chart construction

You need exact trace or layout control beyond a high-level chart helper.

Interactive figure manipulation

You want to add, remove, or update traces after creating a figure.

Serialization and export

You need a structured figure representation for export or transport.

Interview questions

QWhat does plotly.graph_objects provide?

question

Follow-up: How can a graph-object figure be converted for storage or transport? Use methods such as to_dict() or to_json(), depending on whether a Python dictionary or serialized JSON is needed.

QWhat are graph objects in Plotly?

It provides the low-level building blocks for Plotly figures: traces, layouts, and the Figure class. The module uses an automatically generated hierarchy of Python classes that corresponds to the figure schema.

Follow-up: Why might you choose graph_objects over Plotly Express? It gives more direct control over individual traces and layout properties, while Plotly Express creates complete figures through a higher-level API.

QHow is a Figure constructed and manipulated?

Figure accepts data, layout, and frames specifications, which may be supplied using graph objects or dictionaries. The resulting figure can then be manipulated with methods such as add_trace() and update_layout().

Follow-up: What does skip_invalid do in the Figure constructor? When enabled, invalid properties in the figure specification are skipped silently rather than causing validation to fail.

plotly.express
plotly.graph_objects.Figure
plotly.graph_objects.FigureWidget
plotly.graph_objects.Layout
plotly.graph_objects.Scatter
plotly.graph_objects.Bar

Source: Plotly.Graph Objects. Checked 2026-10-15.