diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md index 9c185f7a43..bfc52265d9 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: @@ -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 diff --git a/doc/python/orca-management.md b/doc/python/orca-management.md index 539e85b6b3..d1ca867df5 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 --- +> 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. -> 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. diff --git a/doc/python/static-image-export.md b/doc/python/static-image-export.md index 2b31ba0bdd..692a0f3d79 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. +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 -### Create a Figure - -Now let's create a simple scatter plot with 100 random points of varying color and size. - -```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() -``` +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. -### Write Image File +Run `plotly_get_chrome` to install Chrome. -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. - -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, 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) ~~~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 -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") -``` - -and then display the first 20 bytes. +import plotly.express as px +data_canada = px.data.gapminder().query("country == 'Canada'") +fig = px.bar(data_canada, x='year', y='pop') -```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,11 +172,13 @@ 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: +Here is an example of specifying `orca` for the image export engine: ~~~python fig.to_image(format="png", engine="orca") ~~~ @@ -208,31 +188,80 @@ 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 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 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 (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`. This is deprecated since version 6.1. Use `plotly.io.defaults` instead. + +~~~python +import plotly.io as pio +# Example using deprecated `plotly.io.kaleido.scope` +pio.kaleido.scope.default_format = "jpeg" +~~~ + + + +**Image Export Settings (Orca)** -### 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). +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. diff --git a/doc/python/static-image-generation-migration.md b/doc/python/static-image-generation-migration.md new file mode 100644 index 0000000000..606f01f426 --- /dev/null +++ b/doc/python/static-image-generation-migration.md @@ -0,0 +1,71 @@ +--- +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 + +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. + +To migrate from either Orca or Kaleido v0, first install the latest Kaleido with: + +```bash +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. + +You'll need to update your code to remove references to `engine`. For example, `fig.to_image(format="png", engine="orca")` or `fig.to_image(format="png", engine="kaleido")` needs to be updated to `fig.to_image(format="png")`. This change applies to: `fig.to_image`, `fig.write_image`, `plotly.io.to_image`, and `plotly.io.write_image`. + +## EPS Format + +The `eps` format is no longer supported in Kaleido v1. If your existing code sets `format=eps`, you'll need to update it to use another format, for example `pdf`. + +## Config Settings + +Accessing Kaleido defaults and config settings via `plotly.io.kaleido.scope` is now deprecated and will be removed after September 2025. You'll need to update any code that uses `plotly.io.kaleido.scope` to instead use `plotly.io.defaults`. For example, to set the `default_format` to "jpeg": + +~~~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`. + diff --git a/doc/python/troubleshooting.md b/doc/python/troubleshooting.md index 832abf47da..09c274e3e6 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/) +> 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: