Python > Fundamentals > Static Image Export
Suggest an edit to this page

Static Image Export in Python

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 image.


New to Plotly?

Plotly is a free and open-source graphing library for Python. We recommend you read our Getting Started guide for the latest installation or upgrade instructions, then move on to our Plotly Fundamentals tutorials or dive straight in to some Basic Charts tutorials.

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. This page explains how to do the former.

Install Dependencies

Static image generation requires either Kaleido (recommended, supported as of plotly 4.9) or orca (legacy as of plotly 4.9). The kaleido package can be installed using pip...

$ pip install -U kaleido

or 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 command line utility. See the 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.

In [1]:
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()

Write Image File

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

In [2]:
import os

if not os.path.exists("images"):
    os.mkdir("images")

If you are running this notebook live, click to open the output directory so you can examine the images as they are written.

Raster Formats: PNG, JPEG, and WebP

plotly.py can output figures to several raster image formats including PNG, ...

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

JPEG, ...

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

and WebP

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

Vector Formats: SVG and PDF...

plotly.py can also output figures in several vector formats including SVG, ...

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

PDF, ...

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

and EPS (requires the poppler library)

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

Note: It is important to note that any figures containing WebGL traces (i.e. of type scattergl, heatmapgl, 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 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.

Get started with the official Dash docs and learn how to effortlessly style & deploy apps like this with Dash Enterprise.

Out[3]:

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.

Let convert the figure to a PNG bytes object...

In [4]:
img_bytes = fig.to_image(format="png")

and then display the first 20 bytes.

In [5]:
img_bytes[:20]
Out[5]:
b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x02\xbc'

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!

In [6]:
from IPython.display import Image
Image(img_bytes)
Out[6]:

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.

In [7]:
img_bytes = fig.to_image(format="png", width=600, height=350, scale=2)
Image(img_bytes)
Out[7]:

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:

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")

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

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.
  • mapbox_access_token: The default Mapbox access token.

Image Export Settings (Orca)

See the Orca Management section for information on how to specify image export settings when using 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).

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 at https://dash.plot.ly/installation.

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

import plotly.graph_objects as go # or plotly.express as px
fig = go.Figure() # or any Plotly Express function e.g. px.bar(...)
# fig.add_trace( ... )
# fig.update_layout( ... )

from dash import Dash, dcc, html

app = Dash()
app.layout = html.Div([
    dcc.Graph(figure=fig)
])

app.run_server(debug=True, use_reloader=False)  # Turn off reloader if inside Jupyter