{"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":"python","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":[{"wrong":"from kaleido.scopes.plotly import PlotlyScope","symbol":"Kaleido","correct":"from kaleido import Kaleido"},{"symbol":"write_fig","correct":"from kaleido import write_fig"},{"symbol":"calc_fig","correct":"from kaleido import calc_fig"}],"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+"},{"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.","message":"When 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.","severity":"breaking","affected_versions":"0.0.0+"}],"env_vars":null,"search_vec":"'1.2.0':34 'api':47 'base':22 'bug':39 'current':31 'design':25 'enhanc':43 'ep':18 'export':3,52 'featur':42 'figur':28,54 'fix':40 'generat':11 'imag':13,53 'jpeg':15 'kaleido':1,5 'librari':4,9 'overhaul':48 'pdf':17 'plot':2,51 'plotly.py':27 'png':14 'primarili':24 'receiv':36 'signific':46 'standalon':8 'static':12 'svg':16 'updat':37 'v1.0.0':50 'version':33 'visual':23,55 'web':21 'web-bas':20","created_at":"2026-04-09T03:51:35.671237+00:00","updated_at":"2026-04-16T16:01:16.954385+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.3.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/plotly/kaleido","docs":null,"changelog":null,"pypi":"https://pypi.org/project/kaleido/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":"stale"}}