From 8a787b57bb94aa9a1a3b50aefa83f9dac6902cf0 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 25 Mar 2025 10:21:36 -0400 Subject: [PATCH 01/41] Add deprecation notice for orca --- doc/python/orca-management.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/python/orca-management.md b/doc/python/orca-management.md index 539e85b6b35..2b049687f88 100644 --- a/doc/python/orca-management.md +++ b/doc/python/orca-management.md @@ -5,10 +5,10 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.1' - jupytext_version: 1.1.6 + format_version: '1.3' + jupytext_version: 1.16.4 kernelspec: - display_name: Python 3 + display_name: Python 3 (ipykernel) language: python name: python3 language_info: @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.7.3 + version: 3.11.10 plotly: description: This section covers the low-level details of how plotly.py uses orca to perform static image generation. @@ -33,11 +33,11 @@ jupyter: thumbnail: thumbnail/orca-management.png --- +> Support for orca in Plotly.py is deprecated and will be removed after September 2025. See the [Static Image Export page](/python/static-image-export/) for details on using Kaleido for static image generation. + ### Overview This section covers the lower-level details of how plotly.py can use orca to perform static image generation. -> As of `plotly` version 4.9, Orca is no longer the recommended way to do static image export. We now recommend Kaleido, as described in the [Static Image Export](/python/static-image-export/) section . - Please refer to the [Static Image Export](/python/static-image-export/) section for general information on creating static images from plotly.py figures. ### What is orca? @@ -50,26 +50,26 @@ There are 3 general approaches to installing orca and its Python dependencies. ##### conda Using the [conda](https://conda.io/docs/) package manager, you can install these dependencies in a single command: -``` + $ conda install -c plotly plotly-orca==1.2.1 psutil requests -``` + **Note:** Even if you do not want to use conda to manage your Python dependencies, it is still useful as a cross platform tool for managing native libraries and command-line utilities (e.g. git, wget, graphviz, boost, gcc, nodejs, cairo, etc.). For this use-case, start with [Miniconda](https://conda.io/miniconda.html) (~60MB) and tell the installer to add itself to your system `PATH`. Then run `conda install plotly-orca==1.2.1` and the orca executable will be available system wide. ##### npm + pip You can use the [npm](https://www.npmjs.com/get-npm) package manager to install `orca` (and its `electron` dependency), and then use pip to install `psutil`: -``` + $ npm install -g electron@1.8.4 orca $ pip install psutil requests -``` + ##### Standalone Binaries + pip If you are unable to install conda or npm, you can install orca as a precompiled binary for your operating system. Follow the instructions in the orca [README](https://github.com/plotly/orca) to install orca and add it to your system `PATH`. Then use pip to install `psutil`. -``` + $ pip install psutil requests -``` + ### Install orca on Google Colab @@ -263,4 +263,4 @@ In addition to the `executable` property, the `plotly.io.orca.config` object can ### Saving Configuration Settings -Configuration options can optionally be saved to the `~/.plotly/` directory by calling the `plotly.io.config.save()` method. Saved setting will be automatically loaded at the start of future sessions. \ No newline at end of file +Configuration options can optionally be saved to the `~/.plotly/` directory by calling the `plotly.io.config.save()` method. Saved setting will be automatically loaded at the start of future sessions. From 9dd33301f91196fd3c73f1b14de53f570c809a65 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 25 Mar 2025 10:27:50 -0400 Subject: [PATCH 02/41] Create static-image-generation-migration.md --- .../static-image-generation-migration.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 doc/python/static-image-generation-migration.md diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md new file mode 100644 index 00000000000..631b8234df3 --- /dev/null +++ b/doc/python/static-image-generation-migration.md @@ -0,0 +1,36 @@ +--- +jupyter: + jupytext: + notebook_metadata_filter: all + text_representation: + extension: .md + format_name: markdown + format_version: '1.3' + jupytext_version: 1.16.4 + kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 + language_info: + codemirror_mode: + name: ipython + version: 3 + file_extension: .py + mimetype: text/x-python + name: python + nbconvert_exporter: python + pygments_lexer: ipython3 + version: 3.11.10 + plotly: + description: Details about changes to static image generation in Plotly.py 6.1. + display_as: file_settings + language: python + layout: base + name: Static Image Generation Changes in Plotly.py 6.1 + order: 40 + page_type: u-guide + permalink: python/static-image-generation-changes/ + thumbnail: thumbnail/static-image-export.png +--- + +# Static Image Generation Changes in Plotly.py 6.1 From 97168bfa6b9f57fb3636c9090a68fa76c2943605 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 25 Mar 2025 11:43:51 -0400 Subject: [PATCH 03/41] Add deprecation notice --- doc/python/troubleshooting.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/python/troubleshooting.md b/doc/python/troubleshooting.md index 832abf47daf..34a5ba711be 100644 --- a/doc/python/troubleshooting.md +++ b/doc/python/troubleshooting.md @@ -6,9 +6,9 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.14.1 + jupytext_version: 1.16.4 kernelspec: - display_name: Python 3 + display_name: Python 3 (ipykernel) language: python name: python3 language_info: @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.8.8 + version: 3.11.10 plotly: description: How to troubleshoot import and rendering problems in Plotly with Python. @@ -77,8 +77,7 @@ The situation is similar for environments like Nteract and Streamlit: in these e ### Orca Problems -> Note: as of `plotly` version 4.9, we recommend using [`kaleido`](https://github.com/plotly/Kaleido) -> instead of Orca for [static image export](/python/static-image-export/) +> Support for orca in Plotly.py is deprecated and will be removed after September 2025. See the [Static Image Export page](/python/static-image-export/) for details on using Kaleido for static image generation. If you get an error message stating that the `orca` executable that was found is not valid, this may be because another executable with the same name was found on your system. Please specify the complete path to the Plotly-Orca binary that you downloaded (for instance in the Miniconda folder) with the following command: From ca80cdd17599de90e640ee4a7c185ccd23b2aa35 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 25 Mar 2025 16:36:24 -0400 Subject: [PATCH 04/41] Add info on changes in Plotly.py 6.1 --- .../static-image-generation-migration.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 631b8234df3..46bfddc4ef4 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -33,4 +33,26 @@ jupyter: thumbnail: 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](https://plotly.com/blog/kaleido-the-next-generation/) for Plotly figures. + +While adding support for Kaleido v1, we are deprecating support for earlier versions of Kaleido and support for orca, another static image generation library. Support for earlier verisons of Kaleido and orca will be removed after September 2025, and we recommend updating to the latest Kaleido. This page documents how to migrate to Kaleido v1 and outlines any changes in functionality. + +## Installing Kaleido + +Install the latest kaleido with: + +```bash +pip install -U kaleido +``` + +## Updating Existing Code + +After September 2025, Kaleido v1 will be the sole supported static image generator for Plotly.py. +With this change, the `engine` parameter on Plotly figure methods and functions that generate static images will be removed. For example, `fig.to_image(format="png", engine="orca")` or `fig.to_image(format="png", engine="kaleido")` needs to be updted 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`. + + From 7c76ee31c0fdbf073267100a0b578a53065a51eb Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 25 Mar 2025 16:54:56 -0400 Subject: [PATCH 05/41] Add draft of Kaleido updates --- doc/python/static-image-export.md | 185 +++++++++++++----------------- 1 file changed, 80 insertions(+), 105 deletions(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 2b31ba0bdd6..a0a32a61492 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -5,10 +5,10 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' - jupytext_version: 1.6.0 + format_version: '1.3' + jupytext_version: 1.16.4 kernelspec: - display_name: Python 3 + display_name: Python 3 (ipykernel) language: python name: python3 language_info: @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.7.6 + version: 3.11.10 plotly: description: Plotly allows you to save static images of your plots. Save the image to your local computer, or embed it inside your Jupyter notebooks as a static @@ -35,150 +35,128 @@ jupyter: thumbnail: thumbnail/static-image-export.png --- -### Interactive vs Static Export - -Plotly figures are interactive when viewed in a web browser: you can hover over data points, pan and zoom axes, and show and hide traces by clicking or double-clicking on the legend. You can export figures either to static image file formats like PNG, JPEG, SVG or PDF or you can [export them to HTML files which can be opened in a browser and remain interactive](/python/interactive-html-export/). This page explains how to do the former. - +This page demonstrates how to export interactive Plotly figures to static image formats like PNG, JPEG, SVG, and PDF. If you want to export Plotly figures to HTML to retain interactivity, see the [Interactive HTML Export page](/python/interactive-html-export/) -#### Install Dependencies +## Install Dependencies + +### Kaleido -Static image generation requires either [Kaleido](https://github.com/plotly/Kaleido) (recommended, supported as of `plotly` 4.9) or [orca](https://github.com/plotly/orca) (legacy as of `plotly` 4.9). The `kaleido` package can be installed using pip... +Static image generation requires [Kaleido](https://github.com/plotly/Kaleido). +Install Kaleido with pip: ``` $ pip install -U kaleido ``` - -or conda. +or with conda: ``` $ conda install -c conda-forge python-kaleido ``` -While Kaleido is now the recommended approach, image export can also be supported by the legacy [orca](https://github.com/plotly/orca) command line utility. See the [Orca Management](/python/orca-management/) section for instructions on installing, configuring, and troubleshooting orca. - - - -### Create a Figure - -Now let's create a simple scatter plot with 100 random points of varying color and size. +It's also possible to generate static images using [orca](https://github.com/plotly/orca), though support for orca will be removed after September 2025. See the [Orca Management](/python/orca-management/) page for more details. -```python -import plotly.graph_objects as go -import numpy as np -np.random.seed(1) - -N = 100 -x = np.random.rand(N) -y = np.random.rand(N) -colors = np.random.rand(N) -sz = np.random.rand(N) * 30 - -fig = go.Figure() -fig.add_trace(go.Scatter( - x=x, - y=y, - mode="markers", - marker=go.scatter.Marker( - size=sz, - color=colors, - opacity=0.6, - colorscale="Viridis" - ) -)) - -fig.show() -``` +### Chrome -### Write Image File +Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome. Kaleido v1 and later uses Chrome that's available on the machine on which it's running. If you need to install Chrome for static image generation, Plotly provides a CLI. -The `plotly.io.write_image` function is used to write an image to a file or file-like python object. You can also use the `.write_image` graph object figure method. +Run `plotly_get_chrome` to install Chrome. -Let's first create an output directory to store our images +You can also install Chrome from within Python using `plotly.io.install_chrome()` ```python -import os +import plotly.io as pio -if not os.path.exists("images"): - os.mkdir("images") +pio.install_chrome() ``` + -If you are running this notebook live, click to open the output directory so you can examine the images as they are written. +## Write Image to a File +Plotly figures have a `write_image` method to write a figure to a file. `write_image` supports PNG, JPEG, WebP, SVG, and PDF. -#### Raster Formats: PNG, JPEG, and WebP +To export a figure using `write_image`, call `write_image` on the figure with the filename where you want to save the figure on the figure. The file format is inferred from the extension: -plotly.py can output figures to several raster image formats including **PNG**, ... +### Raster Formats +**PNG** ~~~python -fig.write_image("images/fig1.png") +import plotly.express as px +data_canada = px.data.gapminder().query("country == 'Canada'") +fig = px.bar(data_canada, x='year', y='pop') +fig.write_image("fig1.png") ~~~ -**JPEG**, ... +**JPEG** ~~~python +... fig.write_image("images/fig1.jpeg") ~~~ -and **WebP** +**WebP** ~~~python +... fig.write_image("images/fig1.webp") ~~~ -#### Vector Formats: SVG and PDF... - - -plotly.py can also output figures in several vector formats including **SVG**, ... +### Vector Formats +**SVG** ~~~python +... fig.write_image("images/fig1.svg") ~~~ -**PDF**, ... +**PDF** ~~~python +... fig.write_image("images/fig1.pdf") ~~~ -and **EPS** (requires the poppler library) +--- + +**EPS** (Kaleido<1.0.0) + +Kaleido versions earlier than 1.0.0 also support **EPS** (requires the poppler library) ~~~python +... fig.write_image("images/fig1.eps") ~~~ -**Note:** It is important to note that any figures containing WebGL traces (i.e. of type `scattergl`, `contourgl`, `scatter3d`, `surface`, `mesh3d`, `scatterpolargl`, `cone`, `streamtube`, `splom`, or `parcoords`) that are exported in a vector format will include encapsulated rasters, instead of vectors, for some parts of the image. +**Note:** Figures containing WebGL traces (i.e. of type `scattergl`, `contourgl`, `scatter3d`, `surface`, `mesh3d`, `scatterpolargl`, `cone`, `streamtube`, `splom`, or `parcoords`) that are exported in a vector format will include encapsulated rasters, instead of vectors, for some parts of the image. -### Image Export in Dash -[Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`. +### Specifying a Format -Get started with [the official Dash docs](https://dash.plotly.com/installation) and **learn how to effortlessly [style](https://plotly.com/dash/design-kit/) & [deploy](https://plotly.com/dash/app-manager/) apps like this with Dash Enterprise.** +In the earlier example, Plotly inferred the image format from the extension of the filename. You can also specify this with the `format` parameter. +~~~python +import plotly.express as px +data_canada = px.data.gapminder().query("country == 'Canada'") +fig = px.bar(data_canada, x='year', y='pop') +fig.write_image("fig1", format="png") +~~~ -```python hide_code=true -from IPython.display import IFrame -snippet_url = 'https://python-docs-dash-snippets.herokuapp.com/python-docs-dash-snippets/' -IFrame(snippet_url + 'static-image-export', width='100%', height=1200) -``` -### Get Image as Bytes -The `plotly.io.to_image` function is used to return an image as a bytes object. You can also use the `.to_image` graph object figure method. +## Get Image as Bytes -Let convert the figure to a **PNG** bytes object... +As well as exporting to a file, Plotly figures also support conversion to a bytes object. +To convert a figure to a **PNG** bytes object, call the figure's `to_image` method with a `format` ```python -img_bytes = fig.to_image(format="png") -``` +import plotly.express as px +data_canada = px.data.gapminder().query("country == 'Canada'") +fig = px.bar(data_canada, x='year', y='pop') -and then display the first 20 bytes. - -```python -img_bytes[:20] +img_bytes = fig.to_image(format="png") ``` -#### Display Bytes as Image Using `IPython.display.Image` +### Display Bytes as Image Using `IPython.display.Image` A bytes object representing a PNG image can be displayed directly in the notebook using the `IPython.display.Image` class. This also works in the [Qt Console for Jupyter](https://qtconsole.readthedocs.io/en/stable/)! ```python @@ -186,7 +164,7 @@ from IPython.display import Image Image(img_bytes) ``` -### Change Image Dimensions and Scale +## Change Image Dimensions and Scale In addition to the image format, the `to_image` and `write_image` functions provide arguments to specify the image `width` and `height` in logical pixels. They also provide a `scale` parameter that can be used to increase (`scale` > 1) or decrease (`scale` < 1) the physical resolution of the resulting image. ```python @@ -194,8 +172,10 @@ img_bytes = fig.to_image(format="png", width=600, height=350, scale=2) Image(img_bytes) ``` - -### Specify Image Export Engine +## Specify Image Export Engine + +> The `engine` parameter is deprecated in Plotly.py 6.1.0 and will be removed after September 2025. + If `kaleido` is installed, it will automatically be used to perform image export. If it is not installed, plotly.py will attempt to use `orca` instead. The `engine` argument to the `to_image` and `write_image` functions can be used to override this default behavior. Here is an example of specifying that orca should be used: @@ -208,31 +188,26 @@ And, here is an example of specifying that Kaleido should be used: fig.to_image(format="png", engine="kaleido") ~~~ - -### Image Export Settings (Kaleido) -Various image export settings can be configured using the `plotly.io.kaleido.scope` object. For example, the `default_format` property can be used to specify that the default export format should be `svg` instead of `png` +## plotly.io Functions -```python -import plotly.io as pio -pio.kaleido.scope.default_format = "svg" -``` +Previous examples on this page access `write_image` and `to_image` as methods on Plotly Figure objects. This functionality is also available via the `plotly.io` subpackage. -Here is a complete listing of the available image export settings: +The following example uses the `write_image` function from `plotly.io`. The function takes the figure or a `dict` representing a figure (as shown in the example) as it's first argument. - - **`default_width`**: The default pixel width to use on image export. - - **`default_height`**: The default pixel height to use on image export. - - **`default_scale`**: The default image scale factor applied on image export. - - **`default_format`**: The default image format used on export. One of `"png"`, `"jpeg"`, `"webp"`, `"svg"`, `"pdf"`, or `"eps"`. - - **`mathjax`**: Location of the MathJax bundle needed to render LaTeX characters. Defaults to a CDN location. If fully offline export is required, set this to a local MathJax bundle. - - **`topojson`**: Location of the topojson files needed to render choropleth traces. Defaults to a CDN location. If fully offline export is required, set this to a local directory containing the [Plotly.js topojson files](https://github.com/plotly/plotly.js/tree/master/dist/topojson). - - **`mapbox_access_token`**: The default Mapbox access token. - +~~~python +import plotly.io as pio + -### Image Export Settings (Orca) -See the [Orca Management](/python/orca-management/) section for information on how to specify image export settings when using orca. +fig = dict({ + "data": [{"type": "bar", + "x": [1, 2, 3], + "y": [1, 3, 2]}], + "layout": {"title": {"text": "A Figure Specified By Python Dictionary"}} +}) -### Summary -In summary, to export high-quality static images from plotly.py, all you need to do is install the `kaleido` package and then use the `plotly.io.write_image` and `plotly.io.to_image` functions (or the `.write_image` and `.to_image` graph object figure methods). +pio.write_image(fig, "fig.png") +~~~ + From 2e0b441969495bc33bac1d10a6e567eddba95f2b Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 27 Mar 2025 11:04:06 -0400 Subject: [PATCH 06/41] Add default settings info --- doc/python/static-image-export.md | 48 +++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index a0a32a61492..d2db1d7b11c 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -211,3 +211,51 @@ fig = dict({ pio.write_image(fig, "fig.png") ~~~ + +## Image Export Settings + +As well as configuring height, width, and other settings by passing arguments when calling `write_image` and `to_image`, you can specify defaults to be used. + +### Available Settings + +The following settings are availble. + +`default_width`: The default pixel width to use on image export. + +`default_height`: The default pixel height to use on image export. + +`default_scale`: The default image scale factor applied on image export. + +`default_format`: The default image format used on export. One of "png", "jpeg", "webp", "svg", "pdf", or "eps" (Kaleido v1 only). + +`mathjax`: Location of the MathJax bundle needed to render LaTeX characters. Defaults to a CDN location. If fully offline export is required, set this to a local MathJax bundle. + +`topojson`: Location of the topojson files needed to render choropleth traces. Defaults to a CDN location. If fully offline export is required, set this to a local directory containing the Plotly.js topojson files. + +`mapbox_access_token`: The default Mapbox access token. + +### Configuring Defaults + +Since Plotly.py 6.1, settings are available on `plotly.io.defaults` + +To set the `default_format` to "jpeg": + +~~~python +import plotly.io as pio +pio.defaults.default_format = "jpeg" +~~~ + +You can also access current defaults. To see the default value for height: + +~~~python +import plotly.io as pio +pio.defaults.default_height +~~~ + +In earlier versions of Plotly.py, these settings are available on `plotly.io.kaleido.scope`. This is deprecated since version 6.1. Use `plotly.io.defaults` instead. + +~~~python +import plotly.io as pio +pio.kaleido.scope.default_format = "jpeg" +~~~ + From 577329d76e95c29dce59afb7f8e7eae29b855d6f Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 27 Mar 2025 12:09:58 -0400 Subject: [PATCH 07/41] Make small updates and add back Orca export settings --- doc/python/static-image-export.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index d2db1d7b11c..e3650b334d4 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -130,7 +130,7 @@ fig.write_image("images/fig1.eps") **Note:** Figures containing WebGL traces (i.e. of type `scattergl`, `contourgl`, `scatter3d`, `surface`, `mesh3d`, `scatterpolargl`, `cone`, `streamtube`, `splom`, or `parcoords`) that are exported in a vector format will include encapsulated rasters, instead of vectors, for some parts of the image. -### Specifying a Format +### Specify a Format In the earlier example, Plotly inferred the image format from the extension of the filename. You can also specify this with the `format` parameter. @@ -212,7 +212,7 @@ pio.write_image(fig, "fig.png") ~~~ -## Image Export Settings +## Image Export Settings (Kaleido) As well as configuring height, width, and other settings by passing arguments when calling `write_image` and `to_image`, you can specify defaults to be used. @@ -234,7 +234,7 @@ The following settings are availble. `mapbox_access_token`: The default Mapbox access token. -### Configuring Defaults +### Set Defaults Since Plotly.py 6.1, settings are available on `plotly.io.defaults` @@ -256,6 +256,12 @@ In earlier versions of Plotly.py, these settings are available on `plotly.io.kal ~~~python import plotly.io as pio +# Example using deprecated `plotly.io.kaleido.scope` pio.kaleido.scope.default_format = "jpeg" ~~~ + + +**Image Export Settings (Orca)** + +See the [Orca Management section](https://plotly.com/python/orca-management/) for information on how to specify image export settings when using orca. Support for orca will be removed after September 2025. From 02b31f0cd48c9180a1ff4329c4d46c7bd0cb61bf Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Mon, 31 Mar 2025 12:14:41 -0400 Subject: [PATCH 08/41] Update link --- doc/python/getting-started.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md index 9c185f7a43c..5f79a563631 100644 --- a/doc/python/getting-started.md +++ b/doc/python/getting-started.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.16.1 + jupytext_version: 1.16.4 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.10.14 + version: 3.11.10 plotly: description: Getting Started with Plotly for Python. has_thumbnail: false @@ -41,7 +41,7 @@ The [`plotly` Python library](/python/) is an interactive, [open-source](/python Built on top of the Plotly JavaScript library ([plotly.js](https://plotly.com/javascript/)), `plotly` enables Python users to create beautiful interactive web-based visualizations that can be displayed in Jupyter notebooks, saved to standalone HTML files, or served as part of pure Python-built web applications using Dash. The `plotly` Python library is sometimes referred to as "plotly.py" to differentiate it from the JavaScript library. -Thanks to deep integration with our [Kaleido](https://medium.com/plotly/introducing-kaleido-b03c4b7b1d81) image export utility, `plotly` also provides great support for non-web contexts including desktop editors (e.g. QtConsole, Spyder, PyCharm) and static document publishing (e.g. exporting notebooks to PDF with high-quality vector images). +Thanks to deep integration with our [Kaleido](https://github.com/plotly/Kaleido) image export utility, `plotly` also provides great support for non-web contexts including desktop editors (e.g. QtConsole, Spyder, PyCharm) and static document publishing (e.g. exporting notebooks to PDF with high-quality vector images). This Getting Started guide explains how to install `plotly` and related optional pages. Once you've installed, you can use our documentation in three main ways: From 3281d992909297c4105e86240c151ebbdb18e2b9 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Mon, 31 Mar 2025 13:57:52 -0400 Subject: [PATCH 09/41] Update static-image-export.md --- doc/python/static-image-export.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index e3650b334d4..bd987f250aa 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -226,13 +226,13 @@ The following settings are availble. `default_scale`: The default image scale factor applied on image export. -`default_format`: The default image format used on export. One of "png", "jpeg", "webp", "svg", "pdf", or "eps" (Kaleido v1 only). +`default_format`: The default image format used on export. One of "png", "jpeg", "webp", "svg", "pdf", or "eps" (Kaleido v0 only). `mathjax`: Location of the MathJax bundle needed to render LaTeX characters. Defaults to a CDN location. If fully offline export is required, set this to a local MathJax bundle. `topojson`: Location of the topojson files needed to render choropleth traces. Defaults to a CDN location. If fully offline export is required, set this to a local directory containing the Plotly.js topojson files. -`mapbox_access_token`: The default Mapbox access token. +`mapbox_access_token`: The default Mapbox access token (Kaleido v0 only). Mapbox traces are deprecated. See the [MapLibre Migration](https://plotly.com/python/mapbox-to-maplibre/) page for more details. ### Set Defaults From 2cbd63cae6ba960b4d718e9a7f0975081c720dfc Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Mon, 31 Mar 2025 14:53:24 -0400 Subject: [PATCH 10/41] Update migration guide for Kaleido --- .../static-image-generation-migration.md | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 46bfddc4ef4..93dd4b5dbeb 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -40,19 +40,31 @@ Plotly.py 6.1 introduces support for Kaleido v1, which [improves static image ge While adding support for Kaleido v1, we are deprecating support for earlier versions of Kaleido and support for orca, another static image generation library. Support for earlier verisons of Kaleido and orca will be removed after September 2025, and we recommend updating to the latest Kaleido. This page documents how to migrate to Kaleido v1 and outlines any changes in functionality. -## Installing Kaleido -Install the latest kaleido with: +To migrate from either Orca or Kaleido v0, first install the latest Kaleido with: ```bash pip install -U kaleido ``` -## Updating Existing Code +## Engine Parameter -After September 2025, Kaleido v1 will be the sole supported static image generator for Plotly.py. -With this change, the `engine` parameter on Plotly figure methods and functions that generate static images will be removed. For example, `fig.to_image(format="png", engine="orca")` or `fig.to_image(format="png", engine="kaleido")` needs to be updted to `fig.to_image(format="png")`. +The `engine` parameter on static image export methods and functions is deprecated with this Plotly.py release and will be removed after September 2025. You'll need to update your code to remove references to this parameter. 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`. -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": + +~~~python +import plotly.io as pio +pio.defaults.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 future version of Plotly.py. See [MapLibre Migration ](https://plotly.com/python/mapbox-to-maplibre/) 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`. From 9855b6afc0bd599a64c5a1460c622a41d1ecba4b Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 1 Apr 2025 11:59:43 -0400 Subject: [PATCH 11/41] remove orca section --- doc/python/getting-started.md | 26 ++------------------------ 1 file changed, 2 insertions(+), 24 deletions(-) diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md index 5f79a563631..bfc52265d94 100644 --- a/doc/python/getting-started.md +++ b/doc/python/getting-started.md @@ -184,8 +184,8 @@ See [_Displaying Figures in Python_](/python/renderers/) for more information on plotly.py supports [static image export](https://plotly.com/python/static-image-export/), using the either the [`kaleido`](https://github.com/plotly/Kaleido) -package (recommended, supported as of `plotly` version 4.9) or the [orca](https://github.com/plotly/orca) -command line utility (legacy as of `plotly` version 4.9). +package (recommended, supported as of `plotly` version 4.9) or [`orca`](https://github.com/plotly/orca) +command line utility (deprecated and will be removed after September 2025). #### Kaleido @@ -202,28 +202,6 @@ or conda. $ conda install -c plotly python-kaleido ``` -#### Orca - -While Kaleido is now the recommended image export approach because it is easier to install -and more widely compatible, [static image export](https://plotly.com/python/static-image-export/) -can also be supported -by the legacy [orca](https://github.com/plotly/orca) command line utility and the - [`psutil`](https://github.com/giampaolo/psutil) Python package. - -These dependencies can both be installed using conda: - -``` -conda install -c plotly plotly-orca==1.3.1 psutil -``` - -Or, `psutil` can be installed using pip... - -``` -pip install psutil -``` - -and orca can be installed according to the instructions in the [orca README](https://github.com/plotly/orca). - #### Extended Geo Support Some plotly.py features rely on fairly large geographic shape files. The county From 28e7e197e9db2c917eded8e073620261817a7c28 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 1 Apr 2025 12:03:10 -0400 Subject: [PATCH 12/41] Update static-image-export.md --- doc/python/static-image-export.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index bd987f250aa..e864de7f403 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -52,7 +52,7 @@ or with conda: $ conda install -c conda-forge python-kaleido ``` -It's also possible to generate static images using [orca](https://github.com/plotly/orca), though support for orca will be removed after September 2025. See the [Orca Management](/python/orca-management/) page for more details. +It's also possible to generate static images using [Orca](https://github.com/plotly/orca), though support for Orca will be removed after September 2025. See the [Orca Management](/python/orca-management/) page for more details. ### Chrome @@ -178,7 +178,7 @@ Image(img_bytes) If `kaleido` is installed, it will automatically be used to perform image export. If it is not installed, plotly.py will attempt to use `orca` instead. The `engine` argument to the `to_image` and `write_image` functions can be used to override this default behavior. -Here is an example of specifying that orca should be used: +Here is an example of specifying `orca` for the image export engine: ~~~python fig.to_image(format="png", engine="orca") ~~~ @@ -264,4 +264,4 @@ pio.kaleido.scope.default_format = "jpeg" **Image Export Settings (Orca)** -See the [Orca Management section](https://plotly.com/python/orca-management/) for information on how to specify image export settings when using orca. Support for orca will be removed after September 2025. +See the [Orca Management section](https://plotly.com/python/orca-management/) for information on how to specify image export settings when using Orca. Support for Orca will be removed after September 2025. From e8149ae19e4c63db49fee6b06593433e46c79fdd Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 1 Apr 2025 15:27:17 -0400 Subject: [PATCH 13/41] Small updates --- doc/python/orca-management.md | 2 +- doc/python/troubleshooting.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/python/orca-management.md b/doc/python/orca-management.md index 2b049687f88..d1ca867df59 100644 --- a/doc/python/orca-management.md +++ b/doc/python/orca-management.md @@ -33,7 +33,7 @@ jupyter: thumbnail: thumbnail/orca-management.png --- -> Support for orca in Plotly.py is deprecated and will be removed after September 2025. See the [Static Image Export page](/python/static-image-export/) for details on using Kaleido for static image generation. +> Orca support in Plotly.py is deprecated and will be removed after September 2025. See the [Static Image Export page](/python/static-image-export/) for details on using Kaleido for static image generation. ### Overview This section covers the lower-level details of how plotly.py can use orca to perform static image generation. diff --git a/doc/python/troubleshooting.md b/doc/python/troubleshooting.md index 34a5ba711be..09c274e3e60 100644 --- a/doc/python/troubleshooting.md +++ b/doc/python/troubleshooting.md @@ -77,7 +77,7 @@ The situation is similar for environments like Nteract and Streamlit: in these e ### Orca Problems -> Support for orca in Plotly.py is deprecated and will be removed after September 2025. See the [Static Image Export page](/python/static-image-export/) for details on using Kaleido for static image generation. +> Orca support in Plotly.py is deprecated and will be removed after September 2025. See the [Static Image Export page](/python/static-image-export/) for details on using Kaleido for static image generation. If you get an error message stating that the `orca` executable that was found is not valid, this may be because another executable with the same name was found on your system. Please specify the complete path to the Plotly-Orca binary that you downloaded (for instance in the Miniconda folder) with the following command: From 0b79a1702138ee05bfe33056192a7cc066482a2a Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 1 Apr 2025 15:39:54 -0400 Subject: [PATCH 14/41] Update static-image-generation-migration.md --- doc/python/static-image-generation-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 93dd4b5dbeb..b65d72f39d4 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -38,7 +38,7 @@ jupyter: Plotly.py 6.1 introduces support for Kaleido v1, which [improves static image generation](https://plotly.com/blog/kaleido-the-next-generation/) for Plotly figures. -While adding support for Kaleido v1, we are deprecating support for earlier versions of Kaleido and support for orca, another static image generation library. Support for earlier verisons of Kaleido and orca will be removed after September 2025, and we recommend updating to the latest Kaleido. This page documents how to migrate to Kaleido v1 and outlines any changes in functionality. +While adding support for Kaleido v1, we are deprecating support for earlier versions of Kaleido and support for Orca, another static image generation library. Support for earlier verisons of Kaleido and Orca will be removed after September 2025, and we recommend updating to the latest Kaleido. This page documents how to migrate to Kaleido v1 and outlines any changes in functionality. To migrate from either Orca or Kaleido v0, first install the latest Kaleido with: @@ -53,7 +53,7 @@ The `engine` parameter on static image export methods and functions is deprecate ## 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`. +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 From f5ac772e293a13791fbad94736219ffed1477b43 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 2 Apr 2025 10:29:29 -0400 Subject: [PATCH 15/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index e864de7f403..6404eff2a46 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -56,7 +56,7 @@ It's also possible to generate static images using [Orca](https://github.com/plo ### Chrome -Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome. Kaleido v1 and later uses Chrome that's available on the machine on which it's running. If you need to install Chrome for static image generation, Plotly provides a CLI. +Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome. Kaleido v1 and later uses the Chrome that's available on the machine on which it's running. If you need to install Chrome for static image generation, Plotly provides a CLI. Run `plotly_get_chrome` to install Chrome. From 10e8f207d3c0853c1033418faad1ddbca9d47c87 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 2 Apr 2025 10:29:40 -0400 Subject: [PATCH 16/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 6404eff2a46..24af937c369 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -132,7 +132,7 @@ fig.write_image("images/fig1.eps") ### Specify a Format -In the earlier example, Plotly inferred the image format from the extension of the filename. You can also specify this with the `format` parameter. +In the earlier example, Plotly inferred the image format from the extension of the filename. You can also specify the format explicitly using the `format` parameter. ~~~python import plotly.express as px From bbac70b154052b391d754c0a9c533a0e83927b54 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 2 Apr 2025 10:30:14 -0400 Subject: [PATCH 17/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 24af937c369..c0a297aaf5b 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -194,7 +194,7 @@ fig.to_image(format="png", engine="kaleido") Previous examples on this page access `write_image` and `to_image` as methods on Plotly Figure objects. This functionality is also available via the `plotly.io` subpackage. -The following example uses the `write_image` function from `plotly.io`. The function takes the figure or a `dict` representing a figure (as shown in the example) as it's first argument. +The following example uses the `write_image` function from `plotly.io`. The function takes the figure or a `dict` representing a figure (as shown in the example) as its first argument. ~~~python From 9ad552e124787a33adb719e5c2ebb2385507d31b Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 2 Apr 2025 10:30:34 -0400 Subject: [PATCH 18/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index c0a297aaf5b..af133ddd3fc 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -214,7 +214,7 @@ pio.write_image(fig, "fig.png") ## Image Export Settings (Kaleido) -As well as configuring height, width, and other settings by passing arguments when calling `write_image` and `to_image`, you can specify defaults to be used. +As well as configuring height, width, and other settings by passing arguments when calling `write_image` and `to_image`, you can also set a single default to be used throughout the duration of the program. ### Available Settings From c290b5f80cf663f7ab85c1ea9de64020bebabe9d Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 2 Apr 2025 15:41:55 -0400 Subject: [PATCH 19/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index af133ddd3fc..692a0f3d798 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -73,7 +73,7 @@ pio.install_chrome() Plotly figures have a `write_image` method to write a figure to a file. `write_image` supports PNG, JPEG, WebP, SVG, and PDF. -To export a figure using `write_image`, call `write_image` on the figure with the filename where you want to save the figure on the figure. The file format is inferred from the extension: +To export a figure using `write_image`, call `write_image` on the figure, and pass as an argument the filename where you want to save the figure. The file format is inferred from the extension: ### Raster Formats From 7b8061b08abab14b30a8777d12223b7b8221773d Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 3 Apr 2025 12:28:11 -0400 Subject: [PATCH 20/41] Update static-image-generation-migration.md --- doc/python/static-image-generation-migration.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index b65d72f39d4..606f01f4264 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -40,7 +40,6 @@ Plotly.py 6.1 introduces support for Kaleido v1, which [improves static image ge While adding support for Kaleido v1, we are deprecating support for earlier versions of Kaleido and support for Orca, another static image generation library. Support for earlier verisons of Kaleido and Orca will be removed after September 2025, and we recommend updating to the latest Kaleido. This page documents how to migrate to Kaleido v1 and outlines any changes in functionality. - To migrate from either Orca or Kaleido v0, first install the latest Kaleido with: ```bash @@ -49,7 +48,9 @@ pip install -U kaleido ## Engine Parameter -The `engine` parameter on static image export methods and functions is deprecated with this Plotly.py release and will be removed after September 2025. You'll need to update your code to remove references to this parameter. 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`. +The `engine` parameter on static image export methods and functions is deprecated with this Plotly.py release and will be removed after September 2025. Once the `engine` parameter is removed, static image generation will use `Kaleido` 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 From 6ba54f3eb4fa21bc79735ba0da73f0755a3662a8 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 23 Apr 2025 10:54:39 -0400 Subject: [PATCH 21/41] Update static-image-export.md --- doc/python/static-image-export.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 692a0f3d798..11f6cfa39de 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.16.4 + jupytext_version: 1.17.0 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.11.10 + version: 3.13.2 plotly: description: Plotly allows you to save static images of your plots. Save the image to your local computer, or embed it inside your Jupyter notebooks as a static @@ -58,7 +58,7 @@ It's also possible to generate static images using [Orca](https://github.com/plo Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome. Kaleido v1 and later uses the Chrome that's available on the machine on which it's running. If you need to install Chrome for static image generation, Plotly provides a CLI. -Run `plotly_get_chrome` to install Chrome. +Run `plotly_get_chrome` to install Chrome. You can also install Chrome from within Python using `plotly.io.install_chrome()` @@ -71,14 +71,14 @@ pio.install_chrome() ## Write Image to a File -Plotly figures have a `write_image` method to write a figure to a file. `write_image` supports PNG, JPEG, WebP, SVG, and PDF. +Plotly figures have a `write_image` method to write a figure to a file. `write_image` supports PNG, JPEG, WebP, SVG, and PDF. -To export a figure using `write_image`, call `write_image` on the figure, and pass as an argument the filename where you want to save the figure. The file format is inferred from the extension: +To export a figure using `write_image`, call `write_image` on the figure, and pass as an argument the filename where you want to save the figure. The file format is inferred from the extension: ### Raster Formats -**PNG** +**PNG** ~~~python import plotly.express as px data_canada = px.data.gapminder().query("country == 'Canada'") @@ -145,19 +145,17 @@ fig.write_image("fig1", format="png") ## Get Image as Bytes -As well as exporting to a file, Plotly figures also support conversion to a bytes object. +As well as exporting to a file, Plotly figures also support conversion to a bytes object. To convert a figure to a **PNG** bytes object, call the figure's `to_image` method with a `format` ```python import plotly.express as px data_canada = px.data.gapminder().query("country == 'Canada'") fig = px.bar(data_canada, x='year', y='pop') - img_bytes = fig.to_image(format="png") ``` -### Display Bytes as Image Using `IPython.display.Image` -A bytes object representing a PNG image can be displayed directly in the notebook using the `IPython.display.Image` class. This also works in the [Qt Console for Jupyter](https://qtconsole.readthedocs.io/en/stable/)! +Here's the bytes object displayed using `IPython.display.Image`: ```python from IPython.display import Image @@ -214,11 +212,11 @@ pio.write_image(fig, "fig.png") ## Image Export Settings (Kaleido) -As well as configuring height, width, and other settings by passing arguments when calling `write_image` and `to_image`, you can also set a single default to be used throughout the duration of the program. +As well as configuring height, width, and other settings by passing arguments when calling `write_image` and `to_image`, you can also set a single default to be used throughout the duration of the program. ### Available Settings -The following settings are availble. +The following settings are availble. `default_width`: The default pixel width to use on image export. From 30cc77826c0be7ea831cb12d7f4af270f7edcc28 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 23 Apr 2025 11:01:53 -0400 Subject: [PATCH 22/41] Update doc/python/static-image-generation-migration.md --- doc/python/static-image-generation-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 606f01f4264..2aaed53e37c 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -48,7 +48,7 @@ pip install -U kaleido ## Engine Parameter -The `engine` parameter on static image export methods and functions is deprecated with this Plotly.py release and will be removed after September 2025. Once the `engine` parameter is removed, static image generation will use `Kaleido` if it's installed or raise an error if it isn't. +The `engine` parameter on static image export methods and functions is deprecated in Plotly.py 6.1 and will be removed after September 2025. Once the `engine` parameter is removed, static image generation will use `Kaleido` 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`. From 077a3563d6d98e0380f5c09b17e2a90c4206b5a1 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 29 Apr 2025 16:31:18 -0400 Subject: [PATCH 23/41] Add note on browsers --- doc/python/static-image-export.md | 41 ++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 11f6cfa39de..66430d68e6d 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.17.0 + jupytext_version: 1.17.1 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.13.2 + version: 3.13.3 plotly: description: Plotly allows you to save static images of your plots. Save the image to your local computer, or embed it inside your Jupyter notebooks as a static @@ -56,7 +56,7 @@ It's also possible to generate static images using [Orca](https://github.com/plo ### Chrome -Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome. Kaleido v1 and later uses the Chrome that's available on the machine on which it's running. If you need to install Chrome for static image generation, Plotly provides a CLI. +Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome. Kaleido v1 and later uses Chrome (or Chromium) if it can find a compatible version on the machine on which it's running. If you need to install Chrome for static image generation, Plotly provides a CLI. Run `plotly_get_chrome` to install Chrome. @@ -67,6 +67,9 @@ import plotly.io as pio pio.install_chrome() ``` + +See the **Additional Information on Browsers with Kaleido** section below for more details on browser compatibility for Kaleido. + ## Write Image to a File @@ -216,7 +219,7 @@ As well as configuring height, width, and other settings by passing arguments wh ### Available Settings -The following settings are availble. +The following settings are available. `default_width`: The default pixel width to use on image export. @@ -258,8 +261,34 @@ import plotly.io as pio pio.kaleido.scope.default_format = "jpeg" ~~~ +### Additional Information on Browsers with Kaleido + +When you export images from Plotly.py, Kaleido will attempt to find a version of [Chrome](https://www.google.com/chrome/index.html) or [Chromium](https://www.chromium.org/getting-involved/download-chromium/) that it can use for the export. It checks in the operating system's PATH for the executables with the following names: "chromium", "chromium-browser", "chrome", "Chrome", "google-chrome" "google-chrome-stable", "Chrome.app", "Google Chrome", "Google Chrome.app", and "Google Chrome for Testing". + +Kaleido will also check the following locations: + +**Windows** + +- r"c:\Program Files\Google\Chrome\Application\chrome.exe" +- f"c:\\Users\\{os.environ.get('USER', 'default')}\\AppData\\" +- "Local\\Google\\Chrome\\Application\\chrome.exe" + +**Linux"** +- "/usr/bin/google-chrome-stable" +- "/usr/bin/google-chrome" +- "/usr/bin/chrome" -**Image Export Settings (Orca)** +**Mac OS** -See the [Orca Management section](https://plotly.com/python/orca-management/) for information on how to specify image export settings when using Orca. Support for Orca will be removed after September 2025. +- "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" + +--- + +Most recent versions of Chrome or Chromium should work with Kaleido. When you run `plotly_get_chrome`, [the following Chrome version](https://github.com/plotly/choreographer/blob/main/choreographer/resources/last_known_good_chrome.json#L2C17-L2C30) is installed. + +Other Chromium-based browsers may also work, though Kaleido won't discover them automatically. You can set a browser to use by setting the path to search using an environment variable called `BROWSER_PATH`. For example: + +``` +BROWSER_PATH=/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge +``` From 9f9262bdc6cd55958a94a501581d8741d1a0d204 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:31:47 -0400 Subject: [PATCH 24/41] Update doc/python/static-image-generation-migration.md --- doc/python/static-image-generation-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 2aaed53e37c..6d840e9c47c 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -65,7 +65,7 @@ import plotly.io as pio pio.defaults.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 future version of Plotly.py. See [MapLibre Migration ](https://plotly.com/python/mapbox-to-maplibre/) for more details. +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 ](https://plotly.com/python/mapbox-to-maplibre/) 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`. From 551eaa68db5a6a66cd674eceaac20b8adec884f5 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:35:39 -0400 Subject: [PATCH 25/41] update install commands --- doc/python/getting-started.md | 2 +- doc/python/static-image-export.md | 2 +- doc/python/static-image-generation-migration.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md index bfc52265d94..acc2832027c 100644 --- a/doc/python/getting-started.md +++ b/doc/python/getting-started.md @@ -193,7 +193,7 @@ The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies a using pip... ``` -$ pip install -U kaleido +$ pip install --upgrade kaleido ``` or conda. diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 66430d68e6d..78faf2f8922 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -45,7 +45,7 @@ This page demonstrates how to export interactive Plotly figures to static image Static image generation requires [Kaleido](https://github.com/plotly/Kaleido). Install Kaleido with pip: ``` -$ pip install -U kaleido +$ pip install --upgrade kaleido ``` or with conda: ``` diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 2aaed53e37c..35c13e04ed1 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -43,7 +43,7 @@ While adding support for Kaleido v1, we are deprecating support for earlier vers To migrate from either Orca or Kaleido v0, first install the latest Kaleido with: ```bash -pip install -U kaleido +pip install --upgrade kaleido ``` ## Engine Parameter From 8a8b052ec9775d4774266c0a121cf97f174ea479 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:39:34 -0400 Subject: [PATCH 26/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 78faf2f8922..7da98d25593 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -175,7 +175,7 @@ Image(img_bytes) ## Specify Image Export Engine -> The `engine` parameter is deprecated in Plotly.py 6.1.0 and will be removed after September 2025. +> The `engine` parameter, as well as Orca support, is deprecated in Plotly.py 6.1.0 and will be removed after September 2025. If `kaleido` is installed, it will automatically be used to perform image export. If it is not installed, plotly.py will attempt to use `orca` instead. The `engine` argument to the `to_image` and `write_image` functions can be used to override this default behavior. From fc13f1d8fd9edc712f374c204cea1a2a5b1d5b89 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:42:14 -0400 Subject: [PATCH 27/41] Update doc/python/static-image-generation-migration.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-generation-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 9b3999eb317..c44fbe581a3 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -38,7 +38,7 @@ jupyter: Plotly.py 6.1 introduces support for Kaleido v1, which [improves static image generation](https://plotly.com/blog/kaleido-the-next-generation/) for Plotly figures. -While adding support for Kaleido v1, we are deprecating support for earlier versions of Kaleido and support for Orca, another static image generation library. Support for earlier verisons of Kaleido and Orca will be removed after September 2025, and we recommend updating to the latest Kaleido. This page documents how to migrate to Kaleido v1 and outlines any changes in functionality. +While adding support for Kaleido v1, we are deprecating support for earlier versions of Kaleido and support for [Orca](/python/orca-management/). 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: From 63229fc1ca718ea32c93496a75f1d6667f561d8f Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:42:31 -0400 Subject: [PATCH 28/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 7da98d25593..fdcbb02cdc9 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -263,7 +263,7 @@ pio.kaleido.scope.default_format = "jpeg" ### Additional Information on Browsers with Kaleido -When you export images from Plotly.py, Kaleido will attempt to find a version of [Chrome](https://www.google.com/chrome/index.html) or [Chromium](https://www.chromium.org/getting-involved/download-chromium/) that it can use for the export. It checks in the operating system's PATH for the executables with the following names: "chromium", "chromium-browser", "chrome", "Chrome", "google-chrome" "google-chrome-stable", "Chrome.app", "Google Chrome", "Google Chrome.app", and "Google Chrome for Testing". +When exporting images from Plotly.py, Kaleido will attempt to find a version of [Chrome](https://www.google.com/chrome/index.html) or [Chromium](https://www.chromium.org/getting-involved/download-chromium/) that it can use for the export. It checks in the operating system's PATH for executables with the following names: "chromium", "chromium-browser", "chrome", "Chrome", "google-chrome" "google-chrome-stable", "Chrome.app", "Google Chrome", "Google Chrome.app", and "Google Chrome for Testing". Kaleido will also check the following locations: From 2eeac47d9a0037021be394eac72ed4105529d4a9 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:43:28 -0400 Subject: [PATCH 29/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index fdcbb02cdc9..15201a05abb 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -227,7 +227,7 @@ The following settings are available. `default_scale`: The default image scale factor applied on image export. -`default_format`: The default image format used on export. One of "png", "jpeg", "webp", "svg", "pdf", or "eps" (Kaleido v0 only). +`default_format`: The default image format used on export. One of "png", "jpeg", "webp", "svg", or "pdf". ("eps" support is deprecated and available with Kaleido v0 only) `mathjax`: Location of the MathJax bundle needed to render LaTeX characters. Defaults to a CDN location. If fully offline export is required, set this to a local MathJax bundle. From b42185e07af17c4c2088c4b8f0336d6eeca0087d Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:44:18 -0400 Subject: [PATCH 30/41] Update doc/python/static-image-generation-migration.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-generation-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index c44fbe581a3..c4f85552dbc 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -48,7 +48,7 @@ pip install --upgrade kaleido ## Engine Parameter -The `engine` parameter on static image export methods and functions is deprecated in Plotly.py 6.1 and will be removed after September 2025. Once the `engine` parameter is removed, static image generation will use `Kaleido` if it's installed or raise an error if it isn't. +The `engine` parameter on static image export methods and functions is deprecated in Plotly.py 6.1 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`. From e753b7b4120265e7485829b79ed9f1e8a0983cd3 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:48:09 -0400 Subject: [PATCH 31/41] Update doc/python/static-image-generation-migration.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-generation-migration.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index c4f85552dbc..66b39488e2c 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -63,6 +63,8 @@ Accessing Kaleido defaults and config settings via `plotly.io.kaleido.scope` is ~~~python 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 ](https://plotly.com/python/mapbox-to-maplibre/) for more details. From 9fb73a17531f8f290a6bc7e92a4af1594b340bf3 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:48:22 -0400 Subject: [PATCH 32/41] Update doc/python/static-image-generation-migration.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-generation-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 66b39488e2c..f01ecd1e512 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -54,7 +54,7 @@ You'll need to update your code to remove references to `engine`. For example, ` ## 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`. +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 From 0284d5ebe51410798be38a5739bf95552d711493 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:48:46 -0400 Subject: [PATCH 33/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 15201a05abb..2116def6bef 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -74,7 +74,7 @@ See the **Additional Information on Browsers with Kaleido** section below for mo ## Write Image to a File -Plotly figures have a `write_image` method to write a figure to a file. `write_image` supports PNG, JPEG, WebP, SVG, and PDF. +Plotly figures have a `write_image` method to write a figure to a file. `write_image` supports PNG, JPEG, WebP, SVG, and PDF formats. To export a figure using `write_image`, call `write_image` on the figure, and pass as an argument the filename where you want to save the figure. The file format is inferred from the extension: From ff6206688c899306989b480e6b4e70e7a9c4dc28 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:49:50 -0400 Subject: [PATCH 34/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 2116def6bef..bf354335caf 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -165,7 +165,7 @@ from IPython.display import Image Image(img_bytes) ``` -## Change Image Dimensions and Scale +## Specify Image Dimensions and Scale In addition to the image format, the `to_image` and `write_image` functions provide arguments to specify the image `width` and `height` in logical pixels. They also provide a `scale` parameter that can be used to increase (`scale` > 1) or decrease (`scale` < 1) the physical resolution of the resulting image. ```python From 41d72f03ef0be1eb4de1d4c548a04d8fc56c8e53 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Wed, 30 Apr 2025 15:57:01 -0400 Subject: [PATCH 35/41] Update doc/python/static-image-export.md Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com> --- doc/python/static-image-export.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index bf354335caf..f3a245a23ec 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -56,7 +56,11 @@ It's also possible to generate static images using [Orca](https://github.com/plo ### Chrome -Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome. Kaleido v1 and later uses Chrome (or Chromium) if it can find a compatible version on the machine on which it's running. If you need to install Chrome for static image generation, Plotly provides a CLI. +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. + +If you don't have Chrome installed, you can install it directly from Google following the instructions for your operating system. + +Plotly also provides a CLI for installing Chrome from the command line. Run `plotly_get_chrome` to install Chrome. From a27e2a94ea38988665f8e9e5b0232b66608bf6f2 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 1 May 2025 14:18:48 -0400 Subject: [PATCH 36/41] Update static-image-export.md --- doc/python/static-image-export.md | 38 +++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index f3a245a23ec..53809deed57 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -149,6 +149,44 @@ fig.write_image("fig1", format="png") ~~~ + +### Write Multiple Images + +*Kaleido v1 and later* + +`plotly.io` provides a `write_images` function for writing multiple figures to images. Using `write_images` is faster than calling `fig.write_image` multiple times. + +`write_images` takes a list of figure objects or dicts representing figures as its first argument, `fig`. The second argument `file` is a list of paths to export to. These paths can be specified as `str`s or [`pathlib.Path` objects](https://docs.python.org/3/library/pathlib.html). + +~~~python +import plotly.graph_objects as go +import plotly.express as px +import plotly.io as pio + + +fig1 = go.Figure( + data=go.Scatter(x=[1, 2, 3], y=[4, 5, 6], mode='lines+markers'), + layout=go.Layout(title='Line Chart') +) + +fig2 = go.Figure( + data=go.Bar(x=['A', 'B', 'C'], y=[10, 5, 15]), + layout=go.Layout(title='Bar Chart') +) + +fig3 = px.pie( + values=[30, 20, 10, 40], + names=['A', 'B', 'C', 'D'], + title='Pie Chart' +) + +pio.write_images( + fig=[fig1, fig2, fig3], + file=['export_images/line_chart.png', 'export_images/bar_chart.png', 'export_images/pie_chart.png'] +) +~~~ + + ## Get Image as Bytes From 8e623394094318ddcc7ee32c9934058fb4080ec6 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 1 May 2025 15:06:07 -0400 Subject: [PATCH 37/41] Update static-image-export.md --- doc/python/static-image-export.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 53809deed57..256b16412e5 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -327,9 +327,7 @@ Kaleido will also check the following locations: --- -Most recent versions of Chrome or Chromium should work with Kaleido. When you run `plotly_get_chrome`, [the following Chrome version](https://github.com/plotly/choreographer/blob/main/choreographer/resources/last_known_good_chrome.json#L2C17-L2C30) is installed. - -Other Chromium-based browsers may also work, though Kaleido won't discover them automatically. You can set a browser to use by setting the path to search using an environment variable called `BROWSER_PATH`. For example: +Most recent versions of Chrome or Chromium should work with Kaleido. Other Chromium-based browsers may also work, though Kaleido won't discover them automatically. You can set a browser to use by setting the path to search using an environment variable called `BROWSER_PATH`. For example: ``` BROWSER_PATH=/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge From b8253c41420cf01c181a1323d8cce753b8f429ad Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 1 May 2025 15:09:53 -0400 Subject: [PATCH 38/41] Update static-image-generation-migration.md --- doc/python/static-image-generation-migration.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index f01ecd1e512..56155895620 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.3' - jupytext_version: 1.16.4 + jupytext_version: 1.17.1 kernelspec: display_name: Python 3 (ipykernel) language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.11.10 + version: 3.13.3 plotly: description: Details about changes to static image generation in Plotly.py 6.1. display_as: file_settings @@ -46,6 +46,12 @@ 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](/python/static-image-export/) 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.1 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. @@ -67,7 +73,7 @@ pio.defaults.default_format = "jpeg" # 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 ](https://plotly.com/python/mapbox-to-maplibre/) for more details. +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](https://plotly.com/python/mapbox-to-maplibre/) 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`. From ba8ab3920759830b862d4f1de53c3101fd356f3b Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 1 May 2025 15:11:27 -0400 Subject: [PATCH 39/41] Update static-image-export.md --- doc/python/static-image-export.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 256b16412e5..07dedb5a26f 100644 --- a/doc/python/static-image-export.md +++ b/doc/python/static-image-export.md @@ -126,7 +126,7 @@ fig.write_image("images/fig1.pdf") **EPS** (Kaleido<1.0.0) -Kaleido versions earlier than 1.0.0 also support **EPS** (requires the poppler library) +Kaleido versions earlier than 1.0.0 also support **EPS** (requires the poppler library). If using Kaleido v1 or later, we recommend PDF or SVG format. ~~~python ... From 2cc67f338cfd011f41d85b62c6e2f3004b145dcf Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 1 May 2025 15:13:08 -0400 Subject: [PATCH 40/41] Update getting-started.md --- doc/python/getting-started.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md index acc2832027c..6b4b1686e02 100644 --- a/doc/python/getting-started.md +++ b/doc/python/getting-started.md @@ -183,9 +183,7 @@ See [_Displaying Figures in Python_](/python/renderers/) for more information on ### Static Image Export plotly.py supports [static image export](https://plotly.com/python/static-image-export/), -using the either the [`kaleido`](https://github.com/plotly/Kaleido) -package (recommended, supported as of `plotly` version 4.9) or [`orca`](https://github.com/plotly/orca) -command line utility (deprecated and will be removed after September 2025). +using the [`kaleido`](https://github.com/plotly/Kaleido) package. (Support for the legacy [`orca`](https://github.com/plotly/orca) image export utility is deprecated and will be removed after September 2025.) #### Kaleido From 9be1a49c88064aeda557d3e8ee6990970a4482db Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Thu, 1 May 2025 15:53:40 -0400 Subject: [PATCH 41/41] Update static-image-generation-migration.md --- doc/python/static-image-generation-migration.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md index 56155895620..d12444a2cc8 100644 --- a/doc/python/static-image-generation-migration.md +++ b/doc/python/static-image-generation-migration.md @@ -50,7 +50,7 @@ pip install --upgrade kaleido 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](/python/static-image-export/) on the Static Image Export page for more details on Chome and Kaleido. +See the [Chrome section](/python/static-image-export#chrome) on the Static Image Export page for more details on Chome and Kaleido. ## Engine Parameter @@ -76,4 +76,8 @@ pio.defaults.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](https://plotly.com/python/mapbox-to-maplibre/) 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](/python/static-image-export#write-multiple-images) section for more details.