Skip to content

static-image-generation-migration.md

Latest commit

 

History

History
83 lines (63 loc) · 4.17 KB

static-image-generation-migration.md

File metadata and controls

83 lines (63 loc) · 4.17 KB
jupyter
jupytext kernelspec language_info plotly
notebook_metadata_filter text_representation
all
extension format_name format_version jupytext_version
.md
markdown
1.3
1.17.1
display_name language name
Python 3 (ipykernel)
python
python3
codemirror_mode file_extension mimetype name nbconvert_exporter pygments_lexer version
name version
ipython
3
.py
text/x-python
python
python
ipython3
3.13.3
description display_as language layout name order page_type permalink thumbnail
Details about changes to static image generation in Plotly.py 6.1.
file_settings
python
base
Static Image Generation Changes in Plotly.py 6.1
40
u-guide
python/static-image-generation-changes/
thumbnail/static-image-export.png

Static Image Generation Changes in Plotly.py 6.1

Plotly.py 6.1 introduces support for Kaleido v1, which improves static image generation for Plotly figures.

While adding support for Kaleido v1, we are deprecating support for earlier versions of Kaleido and support for Orca. Support for Orca and earlier versions of Kaleido will be removed after September 2025, and we recommend updating to the latest Kaleido. This page documents how to migrate your Plotly code to Kaleido v1 and outlines the changes in functionality.

To migrate from either Orca or Kaleido v0, first install the latest Kaleido with:

pip install --upgrade kaleido

Chrome

Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome as part of the Kaleido package. Kaleido v1 does not include Chrome; instead, it looks for a compatible version of Chrome (or Chromium) already installed on the machine on which it's running.

See the Chrome section on the Static Image Export page for more details on Chome and Kaleido.

Engine Parameter

The engine parameter on static image export methods and functions is deprecated in Plotly.py 6.2 and will be removed after September 2025. Once the engine parameter is removed, static image generation will use Kaleido v1 if it's installed, or raise an error if it isn't.

You'll need to update your code to remove references to engine. For example, fig.to_image(format="png", engine="orca") or fig.to_image(format="png", engine="kaleido") needs to be updated to fig.to_image(format="png"). This change applies to: fig.to_image, fig.write_image, plotly.io.to_image, and plotly.io.write_image.

EPS Format

The eps format is no longer supported in Kaleido v1. If your existing code sets format="eps", you'll need to update it to use another format, for example pdf.

Config Settings

Accessing Kaleido defaults and config settings via plotly.io.kaleido.scope is now deprecated and will be removed after September 2025. You'll need to update any code that uses plotly.io.kaleido.scope to instead use plotly.io.defaults. For example, to set the default_format to "jpeg":

import plotly.io as pio
pio.defaults.default_format = "jpeg"
# Instead of:
# pio.kaleido.scope.default_format = "jpeg"

The mapbox_access_token config setting is not available on plotly.io.defaults because Mapbox maps are deprecated and will be removed in a future version of Plotly.py. See MapLibre Migration for more details.

If you are migrating from Orca, the following config settings do not apply to Kaleido: server_url, port, timeout, and use_xvfb, but other settings, such as default_format, can be accessed via plotly.io.defaults.

Multiple Image Export

Plotly.py 6.1 includes a write_images function (plotly.io.write_images), which we recommend over write_image when exporting more than one figure. Calling write_images with a list of figures (or dicts representing figures) to export provides better performance than multiple calls with write_image. See the Write Multiple Images section for more details.