From 8a787b57bb94aa9a1a3b50aefa83f9dac6902cf0 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Tue, 25 Mar 2025 10:21:36 -0400 Subject: [PATCH 01/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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/20] 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