Jul 10, 2025 · Jul 22, 2025 · Dec 2, 2024 · Jul 22, 2025 · Jul 22, 2025 · Jul 22, 2025
diff --git a/doc/python/creating-and-updating-figures.md b/doc/python/creating-and-updating-figures.md
diff --git a/doc/python/figure-structure.md b/doc/python/figure-structure.md
diff --git a/doc/python/graph-objects.md b/doc/python/graph-objects.md
diff --git a/doc/python/renderers.md b/doc/python/renderers.md
diff --git a/doc/python/templates.md b/doc/python/templates.md
diff --git a/doc/python/time-series.md b/doc/python/time-series.md
diff --git a/doc/python/v4-migration.md b/doc/python/v4-migration.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,7 +6,9 @@ redirect_from:
		---
		The `plotly` Python package exists to create, manipulate and [render](renderers.md) graphical figures (i.e. charts, plots, maps and diagrams) represented by [data structures also referred to as figures](figure-structure.md). The rendering process uses the [Plotly.js JavaScript library](https://plotly.com/javascript/) under the hood although Python developers using this module very rarely need to interact with the Javascript library directly, if ever. Figures can be represented in Python either as dicts or as instances of the `plotly.graph_objects.Figure` class, and are serialized as text in [JavaScript Object Notation (JSON)](https://json.org/) before being passed to Plotly.js.

	> Note: the recommended entry-point into the plotly package is the [high-level plotly.express module, also known as Plotly Express](plotly-express.md), which consists of Python functions which return fully-populated `plotly.graph_objects.Figure` objects. This page exists to document the structure of the data structure that these objects represent for users who wish to understand more about how to customize them, or assemble them from other `plotly.graph_objects` components.
	!!! note

	The recommended entry-point into the plotly package is the [high-level plotly.express module, also known as Plotly Express](plotly-express.md), which consists of Python functions which return fully-populated `plotly.graph_objects.Figure` objects. This page exists to document the structure of the data structure that these objects represent for users who wish to understand more about how to customize them, or assemble them from other `plotly.graph_objects` components.

		### Figures As Dictionaries

Expand All		@@ -30,7 +32,9 @@ pio.show(fig)

		The [`plotly.graph_objects` module provides an automatically-generated hierarchy of classes](reference/graph_objects/index.md) called ["graph objects"](graph-objects.md) that may be used to represent figures, with a top-level class `plotly.graph_objects.Figure`.

	> Note that the recommended alternative to working with Python dictionaries is to [create entire figures at once using Plotly Express](plotly-express.md) and to manipulate the resulting `plotly.graph_objects.Figure` objects as described in this page, wherever possible, rather than to assemble figures bottom-up from underlying graph objects. See ["When to use Graph Objects"](graph-objects.md).
	!!! note

	The recommended alternative to working with Python dictionaries is to [create entire figures at once using Plotly Express](plotly-express.md) and to manipulate the resulting `plotly.graph_objects.Figure` objects as described in this page, wherever possible, rather than to assemble figures bottom-up from underlying graph objects. See ["When to use Graph Objects"](graph-objects.md).

		Graph objects have several benefits compared to plain Python dictionaries.

Expand Down Expand Up		@@ -321,7 +325,9 @@ fig.show()

		Magic underscore notation is supported throughout the graph objects API, and it can often significantly simplify operations involving deeply nested properties.

	> Note: When you see keyword arguments with underscores passed to a graph object constructor or method, it is almost always safe to assume that it is an application of magic underscore notation. We have to say "almost always" rather than "always" because there are a few property names in the plotly schema that contain underscores: error_x, error_y, error_z, copy_xstyle, copy_ystyle, copy_zstyle, paper_bgcolor, and plot_bgcolor. These were added back in the early days of the library (2012-2013) before we standardized on banning underscores from property names.
	!!! note

	When you see keyword arguments with underscores passed to a graph object constructor or method, it is almost always safe to assume that it is an application of magic underscore notation. We have to say "almost always" rather than "always" because there are a few property names in the plotly schema that contain underscores: error_x, error_y, error_z, copy_xstyle, copy_ystyle, copy_zstyle, paper_bgcolor, and plot_bgcolor. These were added back in the early days of the library (2012-2013) before we standardized on banning underscores from property names.

		#### Updating Figure Layouts

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -5,7 +5,9 @@ description: The structure of a figure - data, traces and layout explained.

		The `plotly` Python package exists to [create, manipulate](creating-and-updating-figures.md) and [render](renderers.md) graphical figures (i.e. charts, plots, maps and diagrams) represented by data structures also referred to as figures. The rendering process uses the [Plotly.js JavaScript library](https://plotly.com/javascript/) under the hood although Python developers using this module very rarely need to interact with the Javascript library directly, if ever. Figures can be represented in Python either as dicts or as instances of the `plotly.graph_objects.Figure` class, and are serialized as text in [JavaScript Object Notation (JSON)](https://json.org/) before being passed to Plotly.js.

	> Note: the recommended entry-point into the plotly package is the [high-level plotly.express module, also known as Plotly Express](plotly-express.md), which consists of Python functions which return fully-populated `plotly.graph_objects.Figure` objects. This page exists to document the architecture of the data structure that these objects represent, for users who wish to understand more about how to customize them, or assemble them from [other `plotly.graph_objects` components](graph-objects.md).
	!!! note

	The recommended entry-point into the plotly package is the [high-level plotly.express module, also known as Plotly Express](plotly-express.md), which consists of Python functions which return fully-populated `plotly.graph_objects.Figure` objects. This page exists to document the architecture of the data structure that these objects represent, for users who wish to understand more about how to customize them, or assemble them from [other `plotly.graph_objects` components](graph-objects.md).

		Viewing the underlying data structure for any `plotly.graph_objects.Figure` object, including those returned by Plotly Express, can be done via `print(fig)` or, in JupyterLab, with the special `fig.show("json")` renderer. Figures also support `fig.to_dict()` and `fig.to_json()` methods. `print()`ing the figure will result in the often-verbose `layout.template` key being represented as ellipses `'...'` for brevity.

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,7 +7,9 @@ The figures created, manipulated and rendered by the plotly Python library are [

		The primary classes defined in the `plotly.graph_objects` module are [`Figure`](reference/graph_objects/Figure.md) and an [`ipywidgets`-compatible variant called `FigureWidget`](figurewidget.md), which both represent entire figures. Instances of these classes have many convenience methods for Pythonically [manipulating their attributes](creating-and-updating-figures.md) (e.g. `.update_layout()` or `.add_trace()`, which all accept ["magic underscore" notation](creating-and-updating-figures.md#magic-underscore-notation)) as well as [rendering them](renderers.md) (e.g. `.show()`) and [exporting them to various formats](static-image-export.md) (e.g. `.to_json()` or `.write_image()` or `.write_html()`).

	> Note: the functions in [Plotly Express](plotly-express.md), which is the recommended entry-point into the `plotly` library, are all built on top of graph objects, and all return instances of `plotly.graph_objects.Figure`.
	!!! note

	The functions in [Plotly Express](plotly-express.md), which is the recommended entry-point into the `plotly` library, are all built on top of graph objects, and all return instances of `plotly.graph_objects.Figure`.

		Every non-leaf attribute of a figure is represented by an instance of a class in the `plotly.graph_objects` hierarchy. For example, a figure `fig` can have an attribute `layout.margin`, which contains attributes `t`, `l`, `b` and `r` which are leaves of the tree: they have no children. The field at `fig.layout` is an object of class [`plotly.graph_objects.Layout`](reference/graph_objects/Layout.md) and `fig.layout.margin` is an object of class `plotly.graph_objects.layout.Margin` which represents the `margin` node, and it has fields `t`, `l`, `b` and `r`, containing the values of the respective leaf-nodes. Note that specifying all of these values can be done without creating intermediate objects using ["magic underscore" notation](creating-and-updating-figures.md#magic-underscore-notation): `go.Figure(layout_margin=dict(t=10, b=10, r=10, l=10))`.

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -48,7 +48,9 @@ Additional contexts are supported by choosing a compatible renderer including th

		Next, we will show how to configure the default renderer. After that, we will describe all of the built-in renderers and discuss why you might choose to use each one.

	> Note: The `renderers` framework is a generalization of the `plotly.offline.iplot` and `plotly.offline.plot` functions that were the recommended way to display figures prior to `plotly.py` version 4. These functions have been reimplemented using the `renderers` framework and are still supported for backward compatibility, but they will not be discussed here.
	!!! note

	The `renderers` framework is a generalization of the `plotly.offline.iplot` and `plotly.offline.plot` functions that were the recommended way to display figures prior to `plotly.py` version 4. These functions have been reimplemented using the `renderers` framework and are still supported for backward compatibility, but they will not be discussed here.


		#### Setting The Default Renderer
Expand All		@@ -61,7 +63,9 @@ pio.renderers

		The default renderer that you see when you display `pio.renderers` might be different than what is shown here. This is because `plotly.py` attempts to autodetect an appropriate renderer at startup. You can change the default renderer by assigning the name of an available renderer to the `pio.renderers.default` property. For example, to switch to the `'browser'` renderer, which opens figures in a tab of the default web browser, you would run the following.

	> Note: Default renderers persist for the duration of a single session, but they do not persist across sessions. If you are working in an `IPython` kernel, this means that default renderers will persist for the life of the kernel, but they will not persist across kernel restarts.
	!!! note

	Default renderers persist for the duration of a single session, but they do not persist across sessions. If you are working in an `IPython` kernel, this means that default renderers will persist for the life of the kernel, but they will not persist across kernel restarts.

		```python
		import plotly.io as pio
Expand Down Expand Up		@@ -93,7 +97,9 @@ This renderer is intended for use in the classic [Jupyter Notebook](https://jupy

		This renderer is a good choice for notebooks that will be exported to HTML files (Either using [nbconvert](https://nbconvert.readthedocs.io/en/latest/) or the "Download as HTML" menu action) because the exported HTML files will work without an Internet connection.

	> Note: Adding the plotly.js bundle to the notebook adds a few megabytes to the notebook size. If you can count on always having an Internet connection, you may want to consider using the `notebook_connected` renderer if notebook size is a constraint.
	!!! note

	Adding the plotly.js bundle to the notebook adds a few megabytes to the notebook size. If you can count on always having an Internet connection, you may want to consider using the `notebook_connected` renderer if notebook size is a constraint.

		###### `notebook_connected`
		This renderer is the same as `notebook` renderer, except the plotly.js JavaScript library bundle is loaded from an online CDN location. This saves a few megabytes in notebook size, but an Internet connection is required in order to display figures that are rendered this way.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -5,7 +5,9 @@ description: Theming and templates with plotly with Python

		The Plotly Python library comes pre-loaded with several themes that you can get started using right away, and it also provides support for creating and registering your own themes.

	> Note on terminology: Theming generally refers to the process of defining default styles for visual elements. Themes in plotly are implemented using objects called templates. Templates are slightly more general than traditional themes because in addition to defining default styles, templates can pre-populate a figure with visual elements like annotations, shapes, images, and more. In the documentation we will refer to the overall process of defining default styles as theming, and when in comes to the plotly API we will talk about how themes are implemented using templates.
	!!! note

	On terminology: Theming generally refers to the process of defining default styles for visual elements. Themes in plotly are implemented using objects called templates. Templates are slightly more general than traditional themes because in addition to defining default styles, templates can pre-populate a figure with visual elements like annotations, shapes, images, and more. In the documentation we will refer to the overall process of defining default styles as theming, and when in comes to the plotly API we will talk about how themes are implemented using templates.

		### Using built-in themes

Expand Down Expand Up		@@ -67,7 +69,9 @@ If a theme is not provided to a Plotly Express function or to a graph object fig

		Here is an example of changing to default theme to `"plotly_white"` and then constructing a scatter plot with Plotly Express without providing a template.

	> Note: Default themes persist for the duration of a single session, but they do not persist across sessions. If you are working in an IPython kernel, this means that default themes will persist for the life of the kernel, but they will not persist across kernel restarts.
	!!! note

	Default themes persist for the duration of a single session, but they do not persist across sessions. If you are working in an IPython kernel, this means that default themes will persist for the life of the kernel, but they will not persist across kernel restarts.

		```python
		import plotly.io as pio
Expand Down Expand Up		@@ -119,7 +123,9 @@ fig.update_layout(title=dict(text="Figure Title"),
		fig.show()
		```

	> Note: this example uses magic underscore notation to write `go.Layout(title=dict(font=dict(...)))` as `go.Layout(title_font=dict(...))`
	!!! note

	This example uses magic underscore notation to write `go.Layout(title=dict(font=dict(...)))` as `go.Layout(title_font=dict(...))`

		#### The template data property

Expand Down Expand Up		@@ -289,7 +295,9 @@ fig.update_layout(template="draft")
		fig.show()
		```

	> Note: this example uses magic underscore notation to write `go.layout.Template(layout=dict(annotations=[...]))` as ``go.layout.Template(layout_annotations=[...])`
	!!! note

	This example uses magic underscore notation to write `go.layout.Template(layout=dict(annotations=[...]))` as ``go.layout.Template(layout_annotations=[...])`

		It is also possible to set your own custom template as the default so that you do not need to pass it by name when constructing graph object figures or calling Plotly Express functions.

Expand Down Expand Up		@@ -431,7 +439,9 @@ pio.templates.default = "draft"
		...
		```

	> Note: In order for the import to succeed, the `my_themes.py` file must be on Python's module search path. See https://docs.python.org/3/tutorial/modules.html#the-module-search-path for more information.
	!!! note

	In order for the import to succeed, the `my_themes.py` file must be on Python's module search path. See https://docs.python.org/3/tutorial/modules.html#the-module-search-path for more information.

		<!-- #endregion -->

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -388,7 +388,9 @@ fig.show()

		The `rangebreaks` attribute available on x- and y-axes of type `date` can be used to hide certain time-periods. In the example below, we show two plots: one in default mode to show gaps in the data, and one where we hide weekends and holidays to show an uninterrupted trading history. Note the smaller gaps between the grid lines for December 21 and January 4, where holidays were removed. Check out the reference for more options: [https://plotly.com/python/reference/layout/xaxis/#layout-xaxis-rangebreaks](reference/graph_objects/layout-package/XAxis.md#plotly.graph_objects.layout.XAxis.rangebreaks)

	> Note: a known limitation of this feature is that it does not support `scattergl` traces. When using this feature on plots with more than a few hundred data points with `px.scatter` or `px.line` or `px.area`, you may need to pass in `render_mode="svg"` to ensure that the underlying trace type is `scatter` and not `scattergl`.
	!!! note

	A known limitation of this feature is that it does not support `scattergl` traces. When using this feature on plots with more than a few hundred data points with `px.scatter` or `px.line` or `px.area`, you may need to pass in `render_mode="svg"` to ensure that the underlying trace type is `scatter` and not `scattergl`.

		```python
		import plotly.express as px
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -180,7 +180,9 @@ When the `print_grid` argument to `make_subplots` is set to `True`, a text repre
		#### New `row_heights` argument to replace `row_width`
		The legacy argument for specifying the relative height of subplot rows was called `row_width`. A new `row_heights` argument has been introduced for this purpose.

	> Note: Although it is not mentioned in the docstring for `plotly.subplots.make_subplots`, the legacy `row_width` argument, with the legacy behavior, is still available in version 4.
	!!! note

	Although it is not mentioned in the docstring for `plotly.subplots.make_subplots`, the legacy `row_width` argument, with the legacy behavior, is still available in version 4.

		In addition to having a more consistent name, values specified to the new `row_heights` argument properly honor the `start_cell` argument. With the legacy `row_width` argument, the list of heights was always interpreted from the bottom row to the top row, even if `start_cell=="top-left"`. With the new `row_heights` argument, the list of heights is interpreted from top to bottom if `start_cell=="top-left"` and from bottom to top if `start_cell=="bottom-left"`.

Expand Down