{"id":1523,"library":"kaleido","title":"Kaleido Plot Export Library","description":"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.","status":"active","version":"1.2.0","language":"en","source_language":"en","source_url":"https://github.com/plotly/kaleido","tags":["plotly","export","image","figure","visualization"],"install":[{"cmd":"pip install kaleido","lang":"bash","label":"Install Kaleido"},{"cmd":"python -m kaleido.cli install","lang":"bash","label":"Install Chromium (if not present)"}],"dependencies":[{"reason":"Required to export plotly.graph_objects.Figure objects. Kaleido v1+ requires plotly>=6.1.1.","package":"plotly","optional":true},{"reason":"A 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.","package":"chromium-browser","optional":false}],"imports":[{"note":"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.","symbol":"PlotlyScope","correct":"from kaleido.scopes.plotly import PlotlyScope"}],"quickstart":{"code":"import plotly.graph_objects as go\nimport plotly.io as pio\nimport os\n\n# Create a simple Plotly figure\nfig = go.Figure(data=[go.Scatter(y=[1, 3, 2])])\n\n# Most common way to use Kaleido: implicitly via plotly.io.write_image\noutput_file = \"my_plot.png\"\ntry:\n    fig.write_image(output_file)\n    print(f\"Plot exported to {output_file}\")\nexcept ValueError as e:\n    print(f\"Error exporting plot: {e}\")\n    print(\"HINT: Ensure Kaleido is installed and a Chromium browser is available on your system or run `python -m kaleido.cli install`.\")\n    # Clean up dummy file if created by partial write\n    if os.path.exists(output_file): os.remove(output_file)\n\n# Example of using Kaleido's explicit sync server for performance (v1.1.0+)\n# This is more advanced and not strictly needed for a single export.\n# import kaleido\n# try:\n#     kaleido.start_sync_server()\n#     fig.write_image(\"my_plot_sync.png\")\n#     print(\"Plot exported to my_plot_sync.png using sync server.\")\n# finally:\n#     kaleido.stop_sync_server()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Upgrade Plotly.py to version 6.1.1 or higher: `pip install \"plotly>=6.1.1\"`","message":"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.","severity":"breaking","affected_versions":"1.0.0+"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"1.0.0+"},{"fix":"Wrap your sequential export calls with `kaleido.start_sync_server()` and `kaleido.stop_sync_server()` to reuse a single Kaleido process.","message":"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.","severity":"gotcha","affected_versions":"1.1.0+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}