Version 4 Migration Guide in Python

Migration guide for upgrading from version 3 to version 4

Plotly Studio: Transform any dataset into an interactive data application in minutes with AI. Try Plotly Studio now.

Upgrading to Version 4¶

Upgrading to version 4 of plotly is a matter of following the instructions in the Getting Started guide and reinstalling the packages, subject to the notices below.

Getting Help¶

If you encounter issues in upgrading from version 3 to version 4, please reach out in our Community Forum or if you've found an issue or regression in version 4, please report a Github Issue

Online features (`plotly.plotly`) moved to `chart-studio` package¶

Prior versions of plotly.py contained functionality for creating figures in both "online" and "offline" modes. In "online" mode figures were uploaded to the Chart Studio cloud (or on-premise) service, whereas in "offline" mode figures were rendered locally. Version 4 of plotly is "offline"-only: all "online" functionality has been removed from the main plotly distribution package and moved to the new chart-studio distribution package.

To migrate version 3 "online" functionality, first install the chart-studio package using pip...

$ pip install chart-studio

or conda.

$ conda install -c plotly chart-studio

Then, update your Python import statements to import "online" functionality from the top-level chart_studio package, rather than the top-level plotly package. For example. replace

from plotly.plotly import plot, iplot

with

from chart_studio.plotly import plot, iplot

Similarly,

Replace plotly.api with chart_studio.api
Replace plotly.dashboard_objs with chart_studio.dashboard_objs
Replace plotly.grid_objs with chart_studio.grid_objs
Replace plotly.presentation_objs with chart_studio.presentation_objs
Replace plotly.widgets with chart_studio.widgets

Offline features (`plotly.offline`) replaced by Renderers framework & HTML export¶

Version 4 introduces a new renderers framework that is a generalization of version 3's plotly.offline.init_notebook_mode and plotly.offline.iplot functions for displaying figures. This is a non-breaking change: the plotly.offline.iplot function is still available and has been reimplemented on top of the renderers framework, so no changes are required when porting to version 4. Going forward, we recommend using the renderers framework directly. See Displaying plotly figures for more information.

In version 3, the plotly.offline.plot function was used to export figures to HTML files. In version 4, this function has been reimplemented on top of the new to_html and write_html functions from the plotly.io module. These functions have a slightly more consistent API (see docstrings for details), and going forward we recommend using them directly when performing HTML export. When working with a graph object figure, these functions are also available as the .to_html and .write_html figure methods.

New default theme¶

An updated "plotly" theme has been enabled by default in version 4.

In [1]:

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

# Make figure with subplots
fig = make_subplots(rows=1, cols=2, specs=[[{"type": "bar"},
                                            {"type": "surface"}]])

# Add bar traces to subplot (1, 1)
fig.add_trace(go.Bar(y=[2, 1, 3]), row=1, col=1)
fig.add_trace(go.Bar(y=[3, 2, 1]), row=1, col=1)
fig.add_trace(go.Bar(y=[2.5, 2.5, 3.5]), row=1, col=1)

# Add surface trace to subplot (1, 2)
# Read data from a csv
z_data = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv")
fig.add_surface(z=z_data)

# Hide legend
fig.update_layout(
    showlegend=False,
    title_text="Default Theme",
    height=500,
    width=800,
)

fig.show()

You can revert to the version 3 figure appearance by disabling the default theme as follows:

In [2]:

import plotly.io as pio
pio.templates.default = "none"

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

# Make figure with subplots
fig = make_subplots(rows=1, cols=2, specs=[[{"type": "bar"},
                                            {"type": "surface"}]])

# Add bar traces to subplot (1, 1)
fig.add_trace(go.Bar(y=[2, 1, 3]), row=1, col=1)
fig.add_trace(go.Bar(y=[3, 2, 1]), row=1, col=1)
fig.add_trace(go.Bar(y=[2.5, 2.5, 3.5]), row=1, col=1)

# Add surface trace to subplot (1, 2)
# Read data from a csv
z_data = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv")
fig.add_surface(z=z_data)

# Hide legend
fig.update_layout(
    showlegend=False,
    title_text="Default Theme Disabled",
    height=500,
    width=800,
)

fig.show()

In [3]:

# Restore default theme
pio.templates.default = "plotly"

See Theming and templates for more information on theming in plotly.py version 4.

Add trace return value¶

In version 3, the add_trace graph object figure method returned a reference to the newly created trace. This was also the case for the add_{trace_type} methods (e.g. add_scatter, add_bar, etc.). In version 4, these methods return a reference to the calling figure. This change was made to support method chaining of figure operations. For example

In [4]:

from plotly.subplots import make_subplots
(make_subplots(rows=1, cols=2)
 .add_scatter(y=[2, 1, 3], row=1, col=1)
 .add_bar(y=[3, 2, 1], row=1, col=2)
 .update_layout(
     title_text="Figure title",
     showlegend=False,
     width=800,
     height=500,
 )
 .show())

Code that relied on the add_* methods to return a reference to the newly created trace will need to be updated to access the trace from the returned figure. This can be done by appending .data[-1] to the add trace expression.

Here is an example of a version 3 code snippet that adds a scatter trace to a figure, assigns the result to a variable named scatter, and then modifies the marker size of the scatter trace.

import plotly.graph_objs as go
fig = go.Figure()
scatter = fig.add_trace(go.Scatter(y=[2, 3, 1]))
scatter.marker.size = 20

In version 4, this would be replaced with the following:

import plotly.graph_objects as go
fig = go.Figure()
scatter = fig.add_trace(go.Scatter(y=[2, 3, 1])).data[-1]
scatter.marker.size = 20

`make_subplots` updates¶

The make_subplots function has been overhauled to support all trace types and to support the integration of Plotly Express. Here are a few changes to be aware of when porting code that uses make_subplots to version 4.

New preferred import location¶

The preferred import location of the make_subplots function is now