Kaleido Plot Export Library

Warnings

• breaking Kaleido v1.0.0 introduced significant breaking changes. The API for direct interaction with Kaleido was rewritten, and it no longer bundles a Chromium executable. If upgrading from Kaleido v0.x, substantial code changes and environment setup for Chrome/Chromium are required.
  Fix: Refer to Kaleido v1.x documentation for new API usage. Ensure a Chromium-based browser is installed and accessible in your PATH, or use `python -m kaleido.cli install` to set one up.
• breaking Kaleido v1.0.0 and later require Plotly.py v6.1.1 or newer for seamless integration. Older versions of Plotly.py are not compatible with Kaleido v1+ and will lead to export failures.
  Fix: Upgrade Plotly.py to version 6.1.1 or higher: `pip install "plotly>=6.1.1"`
• gotcha Kaleido requires a Chromium-based browser (like Google Chrome, Microsoft Edge, or a generic Chromium build) to be installed on your system. It does not bundle one from version 1.0.0 onwards. If a suitable browser is not found, image exports will fail with a `ValueError`.
  Fix: Install a Chromium-based browser or use the Kaleido CLI to install Chromium: `python -m kaleido.cli install`. Ensure the browser is accessible in your system's PATH.
• gotcha For applications performing many sequential image exports, repeatedly starting and stopping the Kaleido process can incur significant overhead. From v1.1.0, a persistent sync server can be used to improve performance.
  Fix: Wrap your sequential export calls with `kaleido.start_sync_server()` and `kaleido.stop_sync_server()` to reuse a single Kaleido process.

Install

• pip install kaleido Install Kaleido
• python -m kaleido.cli install Install Chromium (if not present)

Imports

• PlotlyScope

  from kaleido.scopes.plotly import PlotlyScope

  While less common for direct use with `fig.write_image()`, this is the entry point for configuring Plotly-specific export behavior within Kaleido's API.

Quickstart

This quickstart demonstrates the most common way to use Kaleido: through `plotly.io.write_image()` or directly on a `go.Figure` object. Kaleido is automatically detected and used by Plotly to render the static image. It highlights the importance of having a Chromium browser installed.

import plotly.graph_objects as go
import plotly.io as pio
import os

# Create a simple Plotly figure
fig = go.Figure(data=[go.Scatter(y=[1, 3, 2])])

# Most common way to use Kaleido: implicitly via plotly.io.write_image
output_file = "my_plot.png"
try:
    fig.write_image(output_file)
    print(f"Plot exported to {output_file}")
except ValueError as e:
    print(f"Error exporting plot: {e}")
    print("HINT: Ensure Kaleido is installed and a Chromium browser is available on your system or run `python -m kaleido.cli install`.")
    # Clean up dummy file if created by partial write
    if os.path.exists(output_file): os.remove(output_file)

# Example of using Kaleido's explicit sync server for performance (v1.1.0+)
# This is more advanced and not strictly needed for a single export.
# import kaleido
# try:
#     kaleido.start_sync_server()
#     fig.write_image("my_plot_sync.png")
#     print("Plot exported to my_plot_sync.png using sync server.")
# finally:
#     kaleido.stop_sync_server()