You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Plotly allows you to save static images of your plots. Save the image
26
26
to your local computer, or embed it inside your Jupyter notebooks as a static
@@ -35,167 +35,147 @@ jupyter:
35
35
thumbnail: thumbnail/static-image-export.png
36
36
---
37
37
38
-
### Interactive vs Static Export
39
-
40
-
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.
41
-
38
+
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/)
42
39
43
40
<!-- #region -->
44
-
#### Install Dependencies
41
+
## Install Dependencies
42
+
43
+
### Kaleido
45
44
46
-
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...
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.
57
-
58
-
<!-- #endregion -->
59
-
60
-
### Create a Figure
61
-
62
-
Now let's create a simple scatter plot with 100 random points of varying color and size.
55
+
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.
63
56
64
-
```python
65
-
import plotly.graph_objects as go
66
-
import numpy as np
67
-
np.random.seed(1)
68
-
69
-
N =100
70
-
x = np.random.rand(N)
71
-
y = np.random.rand(N)
72
-
colors = np.random.rand(N)
73
-
sz = np.random.rand(N) *30
74
-
75
-
fig = go.Figure()
76
-
fig.add_trace(go.Scatter(
77
-
x=x,
78
-
y=y,
79
-
mode="markers",
80
-
marker=go.scatter.Marker(
81
-
size=sz,
82
-
color=colors,
83
-
opacity=0.6,
84
-
colorscale="Viridis"
85
-
)
86
-
))
87
-
88
-
fig.show()
89
-
```
57
+
### Chrome
90
58
91
-
### Write Image File
59
+
Kaleido uses Chrome for static image generation. Versions of Kaleido prior to v1 included Chrome. Kaleido v1 and later uses 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.
92
60
93
-
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.
61
+
Run `plotly_get_chrome`to install Chrome.
94
62
95
-
Let's first create an output directory to store our images
63
+
You can also install Chrome from within Python using `plotly.io.install_chrome()`
96
64
97
65
```python
98
-
importos
66
+
importplotly.io as pio
99
67
100
-
ifnot os.path.exists("images"):
101
-
os.mkdir("images")
68
+
pio.install_chrome()
102
69
```
70
+
<!-- #endregion -->
103
71
104
-
If you are running this notebook live, click to open the output directory so you can examine the images as they are written.
72
+
## Write Image to a File
105
73
74
+
Plotly figures have a `write_image` method to write a figure to a file. `write_image` supports PNG, JPEG, WebP, SVG, and PDF.
106
75
107
-
#### Raster Formats: PNG, JPEG, and WebP
76
+
To export a figure using `write_image`, call `write_image` on the figure with the filename where you want to save the figure on the figure. The file format is inferred from the extension:
108
77
109
78
110
-
plotly.py can output figures to several raster image formats including **PNG**, ...
plotly.py can also output figures in several vector formats including **SVG**, ...
103
+
### Vector Formats
132
104
105
+
**SVG**
133
106
~~~python
107
+
...
134
108
fig.write_image("images/fig1.svg")
135
109
~~~
136
110
137
-
**PDF**, ...
111
+
**PDF**
138
112
139
113
~~~python
114
+
...
140
115
fig.write_image("images/fig1.pdf")
141
116
~~~
142
117
143
-
and **EPS** (requires the poppler library)
118
+
---
119
+
120
+
**EPS** (Kaleido<1.0.0)
121
+
122
+
Kaleido versions earlier than 1.0.0 also support **EPS** (requires the poppler library)
144
123
145
124
~~~python
125
+
...
146
126
fig.write_image("images/fig1.eps")
147
127
~~~
148
128
149
-
**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.
150
129
130
+
**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.
151
131
152
-
### Image Export in Dash
153
132
154
-
[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`.
133
+
### Specifying a Format
155
134
156
-
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 <aclass="plotly-red"href="https://plotly.com/dash/">Dash Enterprise</a>.**
135
+
In the earlier example, Plotly inferred the image format from the extension of the filename. You can also specify this with the `format` parameter.
####Display Bytes as Image Using `IPython.display.Image`
159
+
### Display Bytes as Image Using `IPython.display.Image`
182
160
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/)!
183
161
184
162
```python
185
163
from IPython.display import Image
186
164
Image(img_bytes)
187
165
```
188
166
189
-
###Change Image Dimensions and Scale
167
+
## Change Image Dimensions and Scale
190
168
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.
> The `engine` parameter is deprecated in Plotly.py 6.1.0 and will be removed after September 2025.
178
+
199
179
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.
200
180
201
181
Here is an example of specifying that orca should be used:
@@ -208,31 +188,26 @@ And, here is an example of specifying that Kaleido should be used:
208
188
fig.to_image(format="png", engine="kaleido")
209
189
~~~
210
190
211
-
<!-- #endregion -->
212
191
213
192
<!-- #region -->
214
-
### Image Export Settings (Kaleido)
215
-
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`
193
+
## plotly.io Functions
216
194
217
-
```python
218
-
import plotly.io as pio
219
-
pio.kaleido.scope.default_format ="svg"
220
-
```
195
+
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.
221
196
222
-
Here is a complete listing of the available image export settings:
197
+
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 it's first argument.
223
198
224
-
-**`default_width`**: The default pixel width to use on image export.
225
-
-**`default_height`**: The default pixel height to use on image export.
226
-
-**`default_scale`**: The default image scale factor applied on image export.
227
-
-**`default_format`**: The default image format used on export. One of `"png"`, `"jpeg"`, `"webp"`, `"svg"`, `"pdf"`, or `"eps"`.
228
-
-**`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.
229
-
-**`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).
230
-
-**`mapbox_access_token`**: The default Mapbox access token.
231
199
232
-
<!-- #endregion -->
200
+
~~~python
201
+
import plotly.io as pio
202
+
233
203
234
-
### Image Export Settings (Orca)
235
-
See the [Orca Management](/python/orca-management/) section for information on how to specify image export settings when using orca.
204
+
fig =dict({
205
+
"data": [{"type": "bar",
206
+
"x": [1, 2, 3],
207
+
"y": [1, 3, 2]}],
208
+
"layout": {"title": {"text": "A Figure Specified By Python Dictionary"}}
209
+
})
236
210
237
-
### Summary
238
-
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).
0 commit comments