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.
$ pip install -U kaleido
$ 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.
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¶
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
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.
plotly.py can output figures to several raster image formats including PNG, ...
plotly.py can also output figures in several vector formats including SVG, ...
and EPS (requires the poppler library)
Note: It is important to note that any figures containing WebGL traces (i.e. of type
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
Get Image as Bytes¶
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...
img_bytes = fig.to_image(format="png")
and then display the first 20 bytes.
from IPython.display import Image Image(img_bytes)
Change Image Dimensions and Scale¶
In addition to the image format, the
write_image functions provide arguments to specify the image
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.
img_bytes = fig.to_image(format="png", width=600, height=350, scale=2) Image(img_bytes)
Specify Image Export Engine¶
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
write_image functions can be used to override this default behavior.
Here is an example of specifying that orca should be used:
And, here is an example of specifying that Kaleido should be used:
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
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
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.
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.to_image functions (or the
.to_image graph object figure methods).
What About Dash?¶
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( ... ) import dash import dash_core_components as dcc import dash_html_components as html app = dash.Dash() app.layout = html.Div([ dcc.Graph(figure=fig) ]) app.run_server(debug=True, use_reloader=False) # Turn off reloader if inside Jupyter