Plotly · Module

fig.write_image

Exports a Plotly figure as a static PNG, JPEG, WebP, SVG, or PDF file. The output format can be inferred from the destination or supplied explicitly.

How it works

Call this Figure method with a file path or writable object. Plotly converts the figure to a static image, infers the format from the file extension unless format is supplied, and lets you control output dimensions, resolution scaling, and validation.

Syntax

fig.write_image(file, format=None, scale=None, width=None, height=None, validate=True)

Parameters

Name	Type	Description
`fig`	`Union[dict, plotly.graph_objects._figure.Figure]`	Figure object or dict representing a figure.
`file`	`Union[str, pathlib.Path]`	Local file path or writable object, such as a pathlib.Path or open file descriptor.
`format`	`Optional[str]`	Optional output format: png, jpg/jpeg, webp, svg, or pdf; otherwise inferred from file or defaults.
`scale`	`Optional[Union[int, float]]`	Optional export scale factor.
`width`	`Optional[int]`	Optional exported width in layout pixels.
`height`	`Optional[int]`	Optional exported height in layout pixels.
`validate`	`bool`	Whether to validate the figure before image conversion; defaults to True.

Key points

The method performs static export rather than producing an interactive HTML artifact.
Supported output formats include PNG, JPEG, WebP, SVG, and PDF.
The destination can be a path string, pathlib.Path, or another writable destination.
width controls the exported image's layout width.
At scale 1.0, the physical pixel dimension matches the corresponding layout dimension.
validate determines whether Plotly validates the figure before conversion.

Common mistakes

If the filename has no recognized extension and format is omitted, the output uses Plotly's configured default format.
Increasing scale improves resolution but also increases the physical pixel dimensions of the exported image.
Do not add the deprecated engine argument; current documentation indicates it is being removed.

Example: Export a figure to PNG

import plotly.express as px

fig = px.bar(x=["A", "B"], y=[1, 3])
fig.write_image("chart.png", width=800, height=500, scale=2)

Creates a bar chart and exports it as a PNG file with explicit dimensions and higher resolution.

When to use it

Static document graphics

Save a chart for a report or presentation.

Build-time asset export

Generate raster or vector assets in an automated pipeline.

Resolution-controlled raster export

Create high-resolution PNG output for printing.

Interview questions

QWhat does fig.write_image do, and which formats can it produce?

It converts a Plotly figure into a static image and writes the result to a file or writable object. The supported formats are PNG, JPEG, WebP, SVG, and PDF.

Follow-up: How would you export several figures efficiently? Use plotly.io.write_images, which is recommended for multiple figures and can perform better than repeated write_image calls.

QHow is the output format selected?

The file argument accepts a local path, pathlib.Path, or writable object. If format is not specified, Plotly derives it from the file extension when available.

Follow-up: What happens when neither format nor a usable extension is provided? Plotly falls back to plotly.io.defaults.default_format.

QHow do width, height, scale, and validate affect export?

width and height set the exported image's layout dimensions in pixels. scale multiplies the output resolution relative to those layout dimensions, while validate controls whether the figure is checked before conversion.

Follow-up: When would you set scale instead of width and height? Use scale when preserving the figure's layout size while requesting a higher- or lower-resolution raster export.

plotly.io.write_image
plotly.io.write_images
plotly.io.to_image
Figure.to_image

Source: plotly.io.write_image — 7.1.0 documentation. Checked 2026-10-15.