Skip to content

Commit 4682d7b

Browse files
emilyklemilykl
committed
update docs to remove references to kaleido v0 and orca
1 parent baf6d33 commit 4682d7b

5 files changed

Lines changed: 35 additions & 301 deletions

File tree

‎doc/python/getting-started.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -183,11 +183,9 @@ See [_Displaying Figures in Python_](/python/renderers/) for more information on
183183
### Static Image Export
184184

185185
plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
186-
using the [`kaleido`](https://github.com/plotly/Kaleido) package. (Support for the legacy [`orca`](https://github.com/plotly/orca) image export utility is deprecated and will be removed after September 2025.)
186+
using the [`kaleido`](https://github.com/plotly/Kaleido) package (version 1.0.0 or greater).
187187

188-
#### Kaleido
189-
190-
The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies and can be installed
188+
Kaleido has minimal dependencies and can be installed
191189
using pip...
192190

193191
```
@@ -200,6 +198,12 @@ or conda.
200198
$ conda install -c plotly python-kaleido
201199
```
202200

201+
Kaleido requires Chrome or Chromium to generate images. By default, Kaleido will use the Chrome or Chromium version already installed on your system. If you don't have it installed or Kaleido can't find it, you may need to install it by running the command:
202+
203+
`plotly_get_chrome`
204+
205+
on your command line.
206+
203207
### Where to next?
204208

205209
Once you've installed, you can use our documentation in three main ways:

‎doc/python/orca-management.md‎

Lines changed: 1 addition & 231 deletions
Original file line numberDiff line numberDiff line change
@@ -33,234 +33,4 @@ jupyter:
3333
thumbnail: thumbnail/orca-management.png
3434
---
3535

36-
> Orca support in Plotly.py is deprecated and will be removed after September 2025. See the [Static Image Export page](/python/static-image-export/) for details on using Kaleido for static image generation.
37-
38-
### Overview
39-
This section covers the lower-level details of how plotly.py can use orca to perform static image generation.
40-
41-
Please refer to the [Static Image Export](/python/static-image-export/) section for general information on creating static images from plotly.py figures.
42-
43-
### What is orca?
44-
Orca is an [Electron](https://electronjs.org/) application that inputs plotly figure specifications and converts them into static images. Orca can run as a command-line utility or as a long-running server process. In order to provide the fastest possible image export experience, plotly.py launches orca in server mode, and communicates with it over a local port. See https://github.com/plotly/orca for more information.
45-
46-
By default, plotly.py launches the orca server process the first time an image export operation is performed, and then leaves it running until the main Python process exits. Because of this, the first image export operation in an interactive session will typically take a couple of seconds, but then all subsequent export operations will be significantly faster, since the server is already running.
47-
48-
### Installing orca
49-
There are 3 general approaches to installing orca and its Python dependencies.
50-
51-
##### conda
52-
Using the [conda](https://conda.io/docs/) package manager, you can install these dependencies in a single command:
53-
<!-- #raw -->
54-
$ conda install -c plotly plotly-orca==1.2.1 psutil requests
55-
<!-- #endraw -->
56-
57-
**Note:** Even if you do not want to use conda to manage your Python dependencies, it is still useful as a cross platform tool for managing native libraries and command-line utilities (e.g. git, wget, graphviz, boost, gcc, nodejs, cairo, etc.). For this use-case, start with [Miniconda](https://conda.io/miniconda.html) (~60MB) and tell the installer to add itself to your system `PATH`. Then run `conda install plotly-orca==1.2.1` and the orca executable will be available system wide.
58-
59-
##### npm + pip
60-
You can use the [npm](https://www.npmjs.com/get-npm) package manager to install `orca` (and its `electron` dependency), and then use pip to install `psutil`:
61-
62-
<!-- #raw -->
63-
$ npm install -g electron@1.8.4 orca
64-
$ pip install psutil requests
65-
<!-- #endraw -->
66-
67-
##### Standalone Binaries + pip
68-
If you are unable to install conda or npm, you can install orca as a precompiled binary for your operating system. Follow the instructions in the orca [README](https://github.com/plotly/orca) to install orca and add it to your system `PATH`. Then use pip to install `psutil`.
69-
70-
<!-- #raw -->
71-
$ pip install psutil requests
72-
<!-- #endraw -->
73-
74-
<!-- #region -->
75-
### Install orca on Google Colab
76-
```
77-
!pip install plotly>=4.7.1
78-
!wget https://github.com/plotly/orca/releases/download/v1.2.1/orca-1.2.1-x86_64.AppImage -O /usr/local/bin/orca
79-
!chmod +x /usr/local/bin/orca
80-
!apt-get install xvfb libgtk2.0-0 libgconf-2-4
81-
```
82-
83-
Once this is done you can use this code to make, show and export a figure:
84-
85-
```python
86-
import plotly.graph_objects as go
87-
fig = go.Figure( go.Scatter(x=[1,2,3], y=[1,3,2] ) )
88-
fig.write_image("fig1.svg")
89-
fig.write_image("fig1.png")
90-
```
91-
92-
The files can then be downloaded with:
93-
94-
```python
95-
from google.colab import files
96-
files.download('fig1.svg')
97-
files.download('fig1.png')
98-
```
99-
<!-- #endregion -->
100-
101-
### Create a Figure
102-
Now let's create a simple scatter plot with 100 random points of varying color and size.
103-
104-
```python
105-
import plotly.graph_objects as go
106-
107-
import numpy as np
108-
np.random.seed(1)
109-
110-
# Generate scatter plot data
111-
N = 100
112-
x = np.random.rand(N)
113-
y = np.random.rand(N)
114-
colors = np.random.rand(N)
115-
sz = np.random.rand(N) * 30
116-
117-
# Build and display figure
118-
fig = go.Figure()
119-
fig.add_trace(go.Scatter(
120-
x=x,
121-
y=y,
122-
mode="markers",
123-
marker={"size": sz,
124-
"color": colors,
125-
"opacity": 0.6,
126-
"colorscale": "Viridis"
127-
}
128-
))
129-
130-
fig.show()
131-
```
132-
133-
### config
134-
We can use the `plotly.io.orca.config` object to view the current orca configuration settings.
135-
136-
```python
137-
import plotly.io as pio
138-
pio.orca.config
139-
```
140-
141-
### status
142-
We can use the `plotly.io.orca.status` object to see the current status of the orca server
143-
144-
```python
145-
import plotly.io as pio
146-
pio.orca.status
147-
```
148-
149-
Since no image export operations have been performed yet, the orca server is not yet running.
150-
151-
Let's export this figure as an SVG image, and record the runtime.
152-
153-
```python
154-
%%time
155-
import plotly.io as pio
156-
from IPython.display import SVG, display
157-
img_bytes = pio.to_image(fig, format="svg")
158-
display(SVG(img_bytes))
159-
```
160-
161-
By checking the `status` object again, we see that the orca server is now running
162-
163-
```python
164-
import plotly.io as pio
165-
pio.orca.status
166-
```
167-
168-
Let's perform this same export operation again, now that the server is already running.
169-
170-
```python
171-
%%time
172-
import plotly.io as pio
173-
from IPython.display import SVG, display
174-
img_bytes = pio.to_image(fig, format="svg")
175-
display(SVG(img_bytes))
176-
```
177-
178-
The difference in runtime is dramatic. Starting the server and exporting the first image takes a couple seconds, while exporting an image with a running server is much faster.
179-
180-
181-
### Shutdown the Server
182-
By default, the orca server will continue to run until the main Python process exits. It can also be manually shut down by calling the `plotly.io.orca.shutdown_server()` function. Additionally, it is possible to configure the server to shut down automatically after a certain period of inactivity. See the `timeout` configuration parameter below for more information.
183-
184-
Regardless of how the server is shut down, it will start back up automatically the next time an image export operation is performed.
185-
186-
```python
187-
import plotly.io as pio
188-
pio.orca.shutdown_server()
189-
pio.orca.status
190-
```
191-
192-
```python
193-
import plotly.io as pio
194-
img_bytes = pio.to_image(fig, format="svg")
195-
display(SVG(img_bytes))
196-
```
197-
198-
```python
199-
import plotly.io as pio
200-
pio.orca.status
201-
```
202-
203-
<!-- #region -->
204-
### Configuring the Executable
205-
By default, plotly.py searches the `PATH` for an executable named `orca` and checks that it is a valid plotly orca executable. If plotly.py is unable to find the executable, you'll get an error message that looks something like this:
206-
207-
```
208-
----------------------------------------------------------------------------
209-
ValueError:
210-
The orca executable is required in order to export figures as static images,
211-
but it could not be found on the system path.
212-
213-
Searched for executable 'orca' on the following path:
214-
/anaconda3/envs/plotly_env/bin
215-
/usr/local/bin
216-
/usr/bin
217-
/bin
218-
/usr/sbin
219-
/sbin
220-
221-
If you haven't installed orca yet, you can do so using conda as follows:
222-
223-
$ conda install -c plotly plotly-orca==1.2.1
224-
225-
Alternatively, see other installation methods in the orca project README at
226-
https://github.com/plotly/orca.
227-
228-
After installation is complete, no further configuration should be needed.
229-
230-
If you have installed orca, then for some reason plotly.py was unable to
231-
locate it. In this case, set the `plotly.io.orca.config.executable`
232-
property to the full path to your orca executable. For example:
233-
234-
>>> plotly.io.orca.config.executable = '/path/to/orca'
235-
236-
After updating this executable property, try the export operation again.
237-
If it is successful then you may want to save this configuration so that it
238-
will be applied automatically in future sessions. You can do this as follows:
239-
240-
>>> plotly.io.orca.config.save()
241-
242-
If you're still having trouble, feel free to ask for help on the forums at
243-
https://community.plotly.com/c/api/python
244-
----------------------------------------------------------------------------
245-
```
246-
If this happens, follow the instructions in the error message and specify the full path to you orca executable using the `plotly.io.orca.config.executable` configuration property.
247-
<!-- #endregion -->
248-
249-
### Other Configuration Settings
250-
In addition to the `executable` property, the `plotly.io.orca.config` object can also be used to configure the following options:
251-
252-
- **`server_url`**: The URL to an externally running instance of Orca. When this is set, plotly.py will not launch an orca server process and instead use the one provided.
253-
- **`port`**: The specific port to use to communicate with the orca server, or `None` if the port will be chosen automatically.
254-
- **`timeout`**: The number of seconds of inactivity required before the orca server is shut down. For example, if timeout is set to 20, then the orca server will shutdown once is has not been used for at least 20 seconds. If timeout is set to `None` (the default), then the server will not be automatically shut down due to inactivity.
255-
- **`default_width`**: The default pixel width to use on image export.
256-
- **`default_height`**: The default pixel height to use on image export.
257-
- **`default_scale`**: The default image scale factor applied on image export.
258-
- **`default_format`**: The default image format used on export. One of `"png"`, `"jpeg"`, `"webp"`, `"svg"`, `"pdf"`, or `"eps"`.
259-
- **`mathjax`**: Location of the MathJax bundle needed to render LaTeX characters. Defaults to a CDN location. If fully offline export is required, set this to a local MathJax bundle.
260-
- **`topojson`**: Location of the topojson files needed to render choropleth traces. Defaults to a CDN location. If fully offline export is required, set this to a local directory containing the [Plotly.js topojson files](https://github.com/plotly/plotly.js/tree/master/dist/topojson).
261-
- **`mapbox_access_token`**: Mapbox access token required to render `scattermapbox` traces.
262-
- **`use_xvfb`**: Whether to call orca using [Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml) on Linux. Xvfb is needed for orca to work in a Linux environment if an X11 display server is not available. By default, plotly.py will automatically use Xvfb if it is installed, and no active X11 display server is detected. This can be set to `True` to force the use of Xvfb, or it can be set to `False` to disable the use of Xvfb.
263-
264-
265-
### Saving Configuration Settings
266-
Configuration options can optionally be saved to the `~/.plotly/` directory by calling the `plotly.io.config.save()` method. Saved setting will be automatically loaded at the start of future sessions.
36+
> The Orca image-generation utility is no longer supported in Plotly.py as of version 7.0.0. See the [Static Image Export page](/python/static-image-export/) for details on using Kaleido for static image generation.

‎doc/python/renderers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ In general, there are six different approaches you can take in order to display
4545
- Using [Dash](https://dash.plot.ly) in a web app context
4646
- Using a [`FigureWidget` rather than a `Figure`](https://plotly.com/python/figurewidget/) in an [`ipywidgets` context](https://ipywidgets.readthedocs.io/en/stable/)
4747
- By [exporting to an HTML file](https://plotly.com/python/interactive-html-export/) and loading that file in a browser immediately or later
48-
- By [rendering the figure to a static image file using Kaleido](https://plotly.com/python/static-image-export/) such as PNG, JPEG, SVG, PDF or EPS and loading the resulting file in any viewer
48+
- By [rendering the figure to a static image file using Kaleido](https://plotly.com/python/static-image-export/) such as PNG, JPEG, SVG or PDF and loading the resulting file in any viewer
4949

5050
Each of the first four approaches is discussed below.
5151

0 commit comments

Comments
 (0)