Registry / data / kaleido

kaleido

JSON →
library1.2.0pypypi✓ verified 47d ago

Kaleido is a standalone library for generating static images (PNG, JPEG, SVG, PDF, EPS) from web-based visualizations, primarily designed for Plotly.py figures. It is currently at version 1.2.0 and receives updates for bug fixes and feature enhancements, with a significant API overhaul in v1.0.0.

dataserialization
pip install kaleido
Install & Compatibility
Where this runs
tested against v1.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
4/6 runs
4/6 runs
py 3.11
4/6 runs
4/6 runs
py 3.12
4/6 runs
4/6 runs
py 3.13
4/6 runs
4/6 runs
py 3.9
4/6 runs
4/6 runs
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Kaleido
from kaleido import Kaleido
from kaleido.scopes.plotly import PlotlyScope
write_fig
from kaleido import write_fig
calc_fig
from kaleido import calc_fig

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()
Debug
Known issues
breakingKaleido 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.
affects: <1.0.0
breakingKaleido 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"`
affects: 1.0.0+
gotchaKaleido 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.
affects: 1.0.0+
gotchaFor 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.
affects: 1.1.0+
breakingWhen using Kaleido to export figures created with Plotly.py, Plotly.py is a necessary dependency. A `ModuleNotFoundError: No module named 'plotly'` indicates that Plotly.py is not installed in the environment.
fix
Install Plotly.py: `pip install plotly`. For Kaleido v1.0.0 and later, it is recommended to install `plotly>=6.1.1` to ensure compatibility.
affects: 0.0.0+
Upgrade
Version history
1.3.0latest on PyPI
Audit
Dependencies
plotlyoptionalRequired to export plotly.graph_objects.Figure objects. Kaleido v1+ requires plotly>=6.1.1.
chromium-browserrequiredA Chromium-based browser (e.g., Google Chrome, Microsoft Edge) is required for rendering figures. Kaleido no longer bundles Chrome and will look for an existing installation.
Agent activity
91 hits · last 30 days
node
12
seranking-bot
4
ahrefsbot
3
chatgpt-user
2
Amazon
1
mj12bot
1
applebot
1
amazonbot
1
googlebot
1
Resources