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 theInteractive HTML Export page

Install Dependencies¶

Kaleido¶

Static image generation requiresKaleido.Install Kaleido with pip:

$ pip install --upgrade kaleido

or with conda:

$ conda install -c conda-forge python-kaleido

It's also possible to generate static images usingOrca, though support for Orca will be removed after September 2025. See theOrca Management page for more details.

Chrome¶

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

If you don't have Chrome installed, you can install it directly from Google following the instructions for your operating system.

Plotly also provides a CLI for installing Chrome from the command line.

Runplotly_get_chrome to install Chrome.

You can also install Chrome from Python usingplotly.io.get_chrome()

importplotly.ioaspiopio.get_chrome()

See theAdditional Information on Browsers with Kaleido section below for more details on browser compatibility for Kaleido.

Write Image to a File¶

Plotly figures have awrite_image method to write a figure to a file.write_image supports PNG, JPEG, WebP, SVG, and PDF formats.

To export a figure usingwrite_image, callwrite_image on the figure, and pass as an argument the filename where you want to save the figure. The file format is inferred from the extension:

Raster Formats¶

PNG

importplotly.expressaspxdata_canada=px.data.gapminder().query("country == 'Canada'")fig=px.bar(data_canada,x='year',y='pop')fig.write_image("fig1.png")

JPEG

...fig.write_image("images/fig1.jpeg")

WebP

...fig.write_image("images/fig1.webp")

Vector Formats¶

SVG

...fig.write_image("images/fig1.svg")

PDF

...fig.write_image("images/fig1.pdf")

EPS (Kaleido<1.0.0)

Kaleido versions earlier than 1.0.0 also supportEPS (requires the poppler library). If using Kaleido v1 or later, we recommend PDF or SVG format.

...fig.write_image("images/fig1.eps")

Note: Figures containing WebGL traces (i.e. of typescattergl,contourgl,scatter3d,surface,mesh3d,scatterpolargl,cone,streamtube,splom, orparcoords) that are exported in a vector format will include encapsulated rasters, instead of vectors, for some parts of the image.

Specify a Format¶

In the earlier example, Plotly inferred the image format from the extension of the filename. You can also specify the format explicitly using theformat parameter.

importplotly.expressaspxdata_canada=px.data.gapminder().query("country == 'Canada'")fig=px.bar(data_canada,x='year',y='pop')fig.write_image("fig1",format="png")

Write Multiple Images¶

Kaleido v1 and later

plotly.io provides awrite_images function for writing multiple figures to images. Usingwrite_images is faster than callingfig.write_image multiple times.

write_images takes a list of figure objects or dicts representing figures as its first argument,fig. The second argumentfile is a list of paths to export to. These paths can be specified asstrs orpathlib.Path objects.

importplotly.graph_objectsasgoimportplotly.expressaspximportplotly.ioaspiofig1=go.Figure(data=go.Scatter(x=[1,2,3],y=[4,5,6],mode='lines+markers'),layout=go.Layout(title='Line Chart'))fig2=go.Figure(data=go.Bar(x=['A','B','C'],y=[10,5,15]),layout=go.Layout(title='Bar Chart'))fig3=px.pie(values=[30,20,10,40],names=['A','B','C','D'],title='Pie Chart')pio.write_images(fig=[fig1,fig2,fig3],file=['export_images/line_chart.png','export_images/bar_chart.png','export_images/pie_chart.png'])

Get Image as Bytes¶

As well as exporting to a file, Plotly figures also support conversion to a bytes object.To convert a figure to aPNG bytes object, call the figure'sto_image method with aformat

Here's the bytes object displayed usingIPython.display.Image:

Specify Image Dimensions and Scale¶

In addition to the image format, theto_image andwrite_image functions provide arguments to specify the imagewidth andheight in logical pixels. They also provide ascale parameter that can be used to increase (scale > 1) or decrease (scale < 1) the physical resolution of the resulting image.

Specify Image Export Engine¶

Theengine parameter, as well as Orca support, is deprecated in Plotly.py 6.2.0 and will be removed after September 2025.

Ifkaleido is installed, it will automatically be used to perform image export. If it is not installed, plotly.py will attempt to useorca instead. Theengine argument to theto_image andwrite_image functions can be used to override this default behavior.

Here is an example of specifyingorca for the image export engine:

fig.to_image(format="png",engine="orca")

And, here is an example of specifying that Kaleido should be used:

fig.to_image(format="png",engine="kaleido")

plotly.io Functions¶

Previous examples on this page accesswrite_image andto_image as methods on Plotly Figure objects. This functionality is also available via theplotly.io subpackage.

The following example uses thewrite_image function fromplotly.io. The function takes the figure or adict representing a figure (as shown in the example) as its first argument.

importplotly.ioaspiofig=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 (Kaleido)¶

As well as configuring height, width, and other settings by passing arguments when callingwrite_image andto_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.

plotlyjs: Location of the Plotly.js bundle to use. Can be a local file path or URL. By default, Kaleido uses the Plotly.js bundle included with Plotly.py.

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 theMapLibre Migration page for more details.

Set Defaults¶

Since Plotly.py 6.1, settings are available onplotly.io.defaults

To set thedefault_format to "jpeg":

importplotly.ioaspiopio.defaults.default_format="jpeg"

You can also access current defaults. To see the default value for height:

importplotly.ioaspiopio.defaults.default_height

In earlier versions of Plotly.py, these settings are available onplotly.io.kaleido.scope. This is deprecated since version 6.2. Useplotly.io.defaults instead.

importplotly.ioaspio# Example using deprecated `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 ofChrome orChromium 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 calledBROWSER_PATH. For example:

BROWSER_PATH=/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge

What About Dash?¶

Dash is an open-source framework for building analytical applications, with no Javascript required, and it is tightly integrated with the Plotly graphing library.

Learn about how to install Dash athttps://dash.plot.ly/installation.

Everywhere in this page that you seefig.show(), you can display the same figure in a Dash application by passing it to thefigure argument of theGraph component from the built-indash_core_components package like this:

importplotly.graph_objectsasgo# or plotly.express as pxfig=go.Figure()# or any Plotly Express function e.g. px.bar(...)# fig.add_trace( ... )# fig.update_layout( ... )fromdashimportDash,dcc,htmlapp=Dash()app.layout=html.Div([dcc.Graph(figure=fig)])app.run(debug=True,use_reloader=False)# Turn off reloader if inside Jupyter