Exporting Plotly.py Figures to Static Images Using the Kaleido Engine

Desired Outcome

Generate a static image file (PNG, SVG, or PDF) from a Plotly.py figure without manual screenshots, suitable for reports or publications.

Prerequisites

• Plotly.py version 4.9 or newer.
• Kaleido package installed via pip install kaleido.
• System‑level Chromium dependencies (e.g., libnss3, libgbm1, libasound2 on Debian/Ubuntu).

Procedure

1. Import Plotly and create a figure.
2. Call fig.write_image() with the target file name, width, height, and optional scale.
3. Verify the output file.

Example: Scatter plot exported as high‑resolution PNG and SVG

import plotly.express as px

# Create a simple scatter figure
fig = px.scatter(
    x=[1, 2, 3, 4, 5],
    y=[2, 3, 5, 4, 6],
    title="Sample Scatter for Export"
)

# Export PNG at 2× scale (1600×1200 pixels if width/height are 800/600)
fig.write_image("scatter.png", width=800, height=600, scale=2)

# Export SVG (vector text, rasterized WebGL if present)
fig.write_image("scatter.svg")

Key Parameters

Parameter	Effect
width / height	Base pixel dimensions before scaling.
scale	Integer multiplier; scale=2 doubles pixel count, increasing DPI.
format	Inferred from file extension (png, jpg, webp, svg, pdf).

Expected Checks

1. Confirm Kaleido is importable: run python -c \"import kaleido; print(kaleido.__version__)\" in the terminal.
2. After exporting, check file size: ls -lh scatter.png should show a non‑zero size.
3. Validate image type: on Linux/macOS, file scatter.png should return something like PNG image data, 1600 x 1200, 8-bit/color RGB, non-interlaced.
4. For SVG, file scatter.svg should report SVG Scalable Vector Graphics image.
5. Optionally inspect the active engine: python -c \"import plotly.io as pio; print(pio.kaleido.scope)\" (if Kaleido is present).

Limitations and Diagnostic Notes

• Kaleido uses a headless Chromium; if required shared libraries are missing, write_image raises ValueError: No default engine found or hangs.
• WebGL traces (e.g., Scattergl) are rasterized even when exporting to SVG, so the output is not a fully vector graphic.
• Very large datasets can increase rendering time and memory usage; consider down‑sampling or using Scatter instead of Scattergl for export.
• The scale parameter multiplies pixel dimensions; it does not affect vector formats (SVG, PDF) beyond embedding a higher‑resolution raster background if any raster layers exist.

Recovery Options

1. Install Kaleido: pip install --upgrade kaleido.
2. On Debian/Ubuntu, install browser dependencies: apt-get update && apt-get install -y libnss3 libgbm1 libasound2 libxext0 libxkbcommon0 libxcomposite1 libxrandr2 libxrender1 libpango-1.0-0 libgtk-3-0.
3. If using a minimal Docker image, add the above packages to the Dockerfile or use a base image that already includes them (e.g., python:3.11-slim with apt-get install).
4. As a last resort, explicitly set the engine: import plotly.io as pio; pio.kaleido.scope.default_format = \"png\"; pio.write_image(fig, \"fallback.png\") (only if Kaleido is present).

Verification Summary

After completing the steps, a successful export will produce a file that:

• Is non‑zero in size.
• Passes the file command as the expected image type.
• Opens correctly in an image viewer or PDF reader.