From 9fe747b8f56b1bf716bcb1c96002e4018c2eb1e1 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Fri, 20 Jun 2025 12:51:36 -0400 Subject: [PATCH 1/5] add kaleido v1 page --- doc/python/getting-started.md | 4 +- doc/python/static-image-export.md | 300 ++++++++++++++++++++---------- 2 files changed, 199 insertions(+), 105 deletions(-) diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md index 9c185f7a43c..acf5c075516 100644 --- a/doc/python/getting-started.md +++ b/doc/python/getting-started.md @@ -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: @@ -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 2b31ba0bdd6..96e3d318af0 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.17.1 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.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 @@ -35,158 +35,179 @@ 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 +$ pip install --upgrade 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. - - +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. -### Create a Figure +### Chrome -Now let's create a simple scatter plot with 100 random points of varying color and size. +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. -```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() -``` +If you don't have Chrome installed, you can install it directly from Google following the instructions for your operating system. -### Write Image File +Plotly also provides a CLI for installing Chrome from the command line. -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. +See the **Additional Information on Browsers with Kaleido** section below for more details on browser compatibility for Kaleido. + + +## Write Image to a File -#### Raster Formats: PNG, JPEG, and WebP +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: -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). If using Kaleido v1 or later, we recommend PDF or SVG format. ~~~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`. +### Specify 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 the format explicitly using 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 + +### Write Multiple Images -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. +*Kaleido v1 and later* -Let convert the figure to a **PNG** bytes object... +`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. -```python -img_bytes = fig.to_image(format="png") -``` +`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'] +) +~~~ + + -and then display the first 20 bytes. +## Get Image as Bytes + +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[:20] +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 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 @@ -194,11 +215,11 @@ img_bytes = fig.to_image(format="png", width=600, height=350, scale=2) Image(img_bytes) ``` - -### Specify Image Export Engine +## Specify Image Export Engine + 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") ~~~ @@ -208,31 +229,104 @@ 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 +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 its first argument. + + +~~~python import plotly.io as pio -pio.kaleido.scope.default_format = "svg" -``` -Here is a complete listing of the available image export settings: - - **`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. +fig = dict({ + "data": [{"type": "bar", + "x": [1, 2, 3], + "y": [1, 3, 2]}], + "layout": {"title": {"text": "A Figure Specified By Python Dictionary"}} +}) +pio.write_image(fig, "fig.png") +~~~ -### Image Export Settings (Orca) -See the [Orca Management](/python/orca-management/) section for information on how to specify image export settings when using orca. +## 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. + +### Available Settings + +The following settings are available. + +`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", or "pdf". ("eps" support is 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. -### 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). +`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 (Kaleido v0 only). Mapbox traces are deprecated. See the [MapLibre Migration](https://plotly.com/python/mapbox-to-maplibre/) page for more details. + +### Set 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`. + +~~~python +import plotly.io as pio +# Example using `plotly.io.kaleido.scope` +pio.kaleido.scope.default_format = "jpeg" +~~~ + +### Additional Information on Browsers with Kaleido + +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: + +**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" + +**Mac OS** + +- "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" + +--- + +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 214c35b7b6c6e40f805bc951a724cfc0aebb679b Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Fri, 20 Jun 2025 12:54:16 -0400 Subject: [PATCH 2/5] Update requirements.txt --- doc/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 65aa3f0aad4..7bf5c01600f 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,4 +1,4 @@ -plotly==6.0.1 +plotly==6.1.2 jupytext==1.16.4 jupyter-client<7 jupyter From ba8bcad0bbaa82cf323d76de50b92b91b4d75cf9 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Fri, 20 Jun 2025 13:02:33 -0400 Subject: [PATCH 3/5] Update conf.py --- doc/apidoc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/apidoc/conf.py b/doc/apidoc/conf.py index 3c80a1af82f..f3135c16aa3 100644 --- a/doc/apidoc/conf.py +++ b/doc/apidoc/conf.py @@ -26,7 +26,7 @@ # The short X.Y version version = "" # The full version, including alpha/beta/rc tags -release = "6.0.1" +release = "6.1.2" # -- General configuration --------------------------------------------------- From de43923e745cbc535dee73a9445b06cf767a2c85 Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Fri, 20 Jun 2025 13:24:54 -0400 Subject: [PATCH 4/5] Update requirements.txt --- doc/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 7bf5c01600f..ee6e51f2c0b 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -33,7 +33,7 @@ python-frontmatter datashader==0.14.4 pyarrow cufflinks==0.17.3 -kaleido +kaleido==0.2.1 umap-learn==0.5.1 pooch wget From c1a195850f90000a39547bded5f67d714af6f25c Mon Sep 17 00:00:00 2001 From: Liam Connors Date: Fri, 20 Jun 2025 14:28:56 -0400 Subject: [PATCH 5/5] add back ruff changes --- doc/requirements.txt | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 5947089e574..c1cb3c5eb62 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,15 +1,9 @@ plotly==6.1.2 -jupytext==1.16.4 -jupyter-client<7 -jupyter -notebook -pandas==1.4.0 -statsmodels==0.14.2 -scipy==1.9.1 -patsy==0.5.6 -numpy==1.22.4 -plotly-geo -igraph +anywidget +cufflinks==0.17.3 +dash-bio +dask==2022.2.0 +datashader==0.14.4 geopandas==0.8.1 geoparse<=2.0.3 igraph @@ -47,15 +41,8 @@ sphinxcontrib-htmlhelp==2.0.0 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.5 -sphinxcontrib-jsmath==1.0.1 -sphinx_bootstrap_theme -recommonmark -pathlib -python-frontmatter -datashader==0.14.4 -pyarrow -cufflinks==0.17.3 -kaleido +squarify +statsmodels==0.14.2 umap-learn==0.5.1 wget xarray==2022.9.0