|
| 1 | +# Kaleido |
| 2 | + |
| 3 | +Kaleido is a cross-platform library for generating static images for [Plotly][plotly]'s visualization library. |
| 4 | +After installing it, you can use `fig.write_image("filename.png")` to save a plot to a file. |
| 5 | + |
| 6 | +<div align="center"> |
| 7 | + <a href="https://dash.plotly.com/project-maintenance"> |
| 8 | + <img src="https://dash.plotly.com/assets/images/maintained-by-plotly.png" width="400px" alt="Maintained by Plotly"> |
| 9 | + </a> |
| 10 | +</div> |
| 11 | + |
| 12 | +## How It Works |
| 13 | + |
| 14 | +The original version of kaleido included a custom build of the Chrome web browser, |
| 15 | +which made it very large (hundreds of megabytes) and proved very difficult to maintain. |
| 16 | +In contrast, |
| 17 | +this version depends on [choreographer][choreographer], |
| 18 | +a lightweight library that enables remote control of browsers from Python. |
| 19 | +When you ask kaleido to create an image, |
| 20 | +it uses choreographer to run a headless instance of Chrome to render and save your figure. |
| 21 | +Please see choreographer's documentation for details. |
| 22 | + |
| 23 | +> The new version of kaleido is a work on progress; we would be grateful for help testing it and improving it. |
| 24 | +> If you find a bug, please report it in [our GitHub repository][repo], |
| 25 | +> and please include a minimal reproducible example if you can. |
| 26 | +> |
| 27 | +> It would also be very helpful to run the script `src/py/tests/manual.py` |
| 28 | +> and attach its zipped output to your bug report. |
| 29 | +> This will give us detailed information about the precise versions of software you are using |
| 30 | +> and the platform you are running on, |
| 31 | +> which will help us track down problems more quickly. |
| 32 | +
|
| 33 | +## Installation |
| 34 | + |
| 35 | +You can install kaleido from [PyPI][pypi] using pip: |
| 36 | + |
| 37 | +``` |
| 38 | +$ pip install kaleido |
| 39 | +``` |
| 40 | + |
| 41 | +## Use |
| 42 | + |
| 43 | +Versions 4.9 and above of the Plotly Python library will automatically use kaleido for static image export when kaleido is installed. |
| 44 | +For example: |
| 45 | + |
| 46 | +```python |
| 47 | +import plotly.express as px |
| 48 | +fig = px.scatter(px.data.iris(), x="sepal_length", y="sepal_width", color="species") |
| 49 | +fig.write_image("figure.png", engine="kaleido") |
| 50 | +``` |
| 51 | + |
| 52 | +See the [Plotly static image export documentation][plotly-export] for more information. |
| 53 | + |
| 54 | +[choreographer]: https://pypi.org/project/choreographer/ |
| 55 | +[plotly]: https://plotly.com/ |
| 56 | +[plotly-export]: https://plotly.com/python/static-image-export/ |
| 57 | +[pypi]: https://pypi.org/ |
| 58 | +[repo]: https://github.com/plotly/Kaleido |
0 commit comments