Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 42 ยท Getting Started

Show, Save and Export Figures

Display Plotly figures with fig.show and renderers, save them as standalone HTML or JSON, export PNG, SVG and PDF with Kaleido, and tune the toolbar with the config option.

A figure is only useful once someone can see it. Plotly offers many ways to get a figure out of Python: show it in a browser or notebook, save it as a self-contained HTML file, embed it in a web page, serialize it to JSON, or export a static image. This lesson covers each route and the config option that controls the toolbar and behavior of the chart.

fig.show() and renderers

fig.show() opens the chart wherever you are working. The destination is decided by the renderer:

Renderer Where it shows
browser Opens a tab in your default browser (default in a plain Python script)
notebook, notebook_connected Classic Jupyter notebook
jupyterlab, vscode, colab Those environments
iframe Embeds the chart as an iframe, good for large notebooks
png, svg, jpeg Static image output (needs Kaleido)
json Dumps the figure JSON, handy for debugging

Plotly picks a sensible default. You can set it for the whole session or for one call:

Python
import plotly.io as pio

pio.renderers.default = "browser"   # for all later fig.show()
fig.show(renderer="notebook")       # for this call only

Any fig.show() argument beyond the renderer is passed through, including config=..., which we cover below.

This site's runner has no screen, so fig.show() cannot draw here. Everything else in this lesson that produces text (HTML, JSON) runs live. Image export needs Kaleido, which cannot run in the browser, so those snippets are read-only.

Save a standalone HTML file

fig.write_html("chart.html") creates a file that anyone can open in a browser, with no Python and no server. The file contains the figure data and, by default, the whole plotly.js library (about 4 to 5 MB). Three options control that:

include_plotlyjs Result
True (default) plotly.js is embedded in the file: works offline, large file
"cdn" The file loads plotly.js from a CDN: small file, needs internet
"directory" Saves plotly.min.js next to the HTML file and links to it
False No library: you load plotly.js yourself, for pages with many charts

full_html=False gives you only a <div> and a <script>, to paste into an existing page. to_html() returns the same text as a string instead of writing a file.

Python Create embeddable HTML

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The snippet is just a div plus a script that calls Plotly.newPlot with your figure's JSON. That is what fig.show() generates for you behind the scenes.

Figures as JSON

Because a figure is just data, you can store it as text and rebuild it later or in another program, even in another language:

Python
import plotly.io as pio

fig.write_json("figure.json")
fig2 = pio.read_json("figure.json")

pio.to_json(fig) and pio.from_json(text) work with strings. The JSON is exactly what plotly.js expects, so a JavaScript page can call Plotly.newPlot(div, obj.data, obj.layout) on it. That makes JSON the bridge between a Python back end and a JavaScript front end.

Python Round-trip a figure through JSON

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

json.dumps(slim) shows how small a figure becomes without the template; templates add several kilobytes of styling to every figure, and later lessons show how to control them.

Draw the same JSON with plotly.js

To prove the point, this page-sized example uses a JSON string (the kind to_json() returns, shortened) and gives it to plotly.js. It also sets the config option, which controls the toolbar and interactions of the chart.

From JSON to chart, with a config

Hover over the chart: the toolbar (camera icon for a PNG download, zoom, pan, reset) appears in the top right corner.

The config option

config customizes behavior that is not part of the figure itself. Pass it to fig.show, write_html or to_html:

Python
fig.show(config={
    "displayModeBar": True,       # always show the toolbar ("hover" is the default)
    "displaylogo": False,
    "scrollZoom": True,
    "doubleClick": "reset",
    "modeBarButtonsToRemove": ["lasso2d", "select2d"],
    "toImageButtonOptions": {"format": "svg", "filename": "report", "height": 600, "width": 900},
    "staticPlot": False,          # True: no interactivity at all
})

Useful settings:

  • displayModeBar: False hides the toolbar completely; True always shows it.
  • staticPlot: True turns the chart into a non-interactive picture, good for thumbnails.
  • editable: True lets viewers edit titles and legend names by clicking.
  • responsive: resizes the chart with the window (already the default for Python output).
  • locale: translate tooltips and the toolbar, for example "de" or "es" (needs the locale file in plotly.js).

Static images with Kaleido

Reports, slides and PDFs need static images. Plotly uses the Kaleido package for that:

Terminal
pip install -U kaleido
Python
fig.write_image("chart.png")                       # format from the extension
fig.write_image("chart.svg")
fig.write_image("chart.pdf", width=900, height=500)
fig.write_image("[email protected]", scale=2)           # sharper image
png_bytes = fig.to_image(format="png", width=800, height=450)

Kaleido 1.x needs a Chrome installation on the machine (plotly_get_chrome installs one). Without Kaleido, to_image raises a RuntimeError saying so. The same chart can also be downloaded by the viewer through the camera button, which uses toImageButtonOptions.

Embedding in web frameworks

  • Flask / Django / Laravel: render fig.to_html(full_html=False, include_plotlyjs="cdn") into a template, or send fig.to_json() from an API endpoint and let plotly.js draw it.
  • Streamlit: st.plotly_chart(fig) (see the Streamlit charts lesson).
  • Dash: put the figure in a dcc.Graph component; later lessons in this course cover it.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which write_html option keeps the file small by loading plotly.js from the internet?

    include_plotlyjs="cdn" references the library by URL instead of embedding about 4 MB of JavaScript.
  2. 2. What does fig.to_json() return?

    The JSON is the figure specification that plotly.js understands, so it can be stored or sent over a network.
  3. 3. Which package is needed for fig.write_image("chart.png")?

    Plotly delegates static image export to Kaleido.
  4. 4. Which config key removes the toolbar entirely?

    displayModeBar: False hides it; staticPlot: True additionally disables all interactivity.
  5. 5. You want to put 10 charts on one web page without downloading plotly.js 10 times. What do you do?

    Include the library once in the page and generate the other charts without it.

Summary

  • fig.show() uses a renderer (browser, notebook, jupyterlab, iframe ...); set the default with pio.renderers.default.
  • write_html / to_html create standalone or embeddable HTML; include_plotlyjs controls whether the library is embedded, linked or omitted.
  • to_json, write_json, from_json and read_json move figures between programs and languages.
  • config controls toolbar, scroll zoom, static mode and the image download button.
  • write_image needs Kaleido and gives PNG, SVG, JPEG, WebP and PDF.

Next: Line Charts