Orca Management in Python

This section covers the low-level details of how plotly.py uses orca to perform static image generation.

Plotly Studio: Transform any dataset into an interactive data application in minutes with AI. Try Plotly Studio now.

Orca support in Plotly.py is deprecated and will be removed after September 2025. See the Static Image Export page for details on using Kaleido for static image generation.

Overview¶

This section covers the lower-level details of how plotly.py can use orca to perform static image generation.

Please refer to the Static Image Export section for general information on creating static images from plotly.py figures.

What is orca?¶

Orca is an Electron 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.

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.

Installing orca¶

There are 3 general approaches to installing orca and its Python dependencies.

conda¶

Using the conda package manager, you can install these dependencies in a single command:

$ conda install -c plotly plotly-orca==1.2.1 psutil requests

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 (~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.

npm + pip¶

You can use the npm package manager to install orca (and its electron dependency), and then use pip to install psutil:

$ npm install -g electron@1.8.4 orca $ pip install psutil requests

Standalone Binaries + pip¶

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 to install orca and add it to your system PATH. Then use pip to install psutil.

$ pip install psutil requests

Install orca on Google Colab¶

!pip install plotly>=4.7.1
!wget https://github.com/plotly/orca/releases/download/v1.2.1/orca-1.2.1-x86_64.AppImage -O /usr/local/bin/orca
!chmod +x /usr/local/bin/orca
!apt-get install xvfb libgtk2.0-0 libgconf-2-4

Once this is done you can use this code to make, show and export a figure:

import plotly.graph_objects as go
fig = go.Figure( go.Scatter(x=[1,2,3], y=[1,3,2] ) )
fig.write_image("fig1.svg")
fig.write_image("fig1.png")

The files can then be downloaded with:

from google.colab import files
files.download('fig1.svg')
files.download('fig1.png')

Create a Figure¶

Now let's create a simple scatter plot with 100 random points of varying color and size.

In [1]:

import plotly.graph_objects as go

import numpy as np
np.random.seed(1)

# Generate scatter plot data
N = 100
x = np.random.rand(N)
y = np.random.rand(N)
colors = np.random.rand(N)
sz = np.random.rand(N) * 30

# Build and display figure
fig = go.Figure()
fig.add_trace(go.Scatter(
    x=x,
    y=y,
    mode="markers",
    marker={"size": sz,
            "color": colors,
            "opacity": 0.6,
            "colorscale": "Viridis"
            }
))

fig.show()

config¶

We can use the plotly.io.orca.config object to view the current orca configuration settings.

In [2]:

import plotly.io as pio
pio.orca.config

Out[2]:

orca configuration
------------------
    server_url: None
    executable: orca
    port: None
    timeout: None
    default_width: None
    default_height: None
    default_scale: 1
    default_format: png
    mathjax: https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js
    topojson: None
    mapbox_access_token: None
    use_xvfb: auto

constants
---------
    plotlyjs: /home/circleci/project/doc/.venv/lib/python3.9/site-packages/plotly/package_data/plotly.min.js
    config_file: /home/circleci/.plotly/.orca

status¶

We can use the plotly.io.orca.status object to see the current status of the orca server

In [3]:

import plotly.io as pio
pio.orca.status

Out[3]:

orca status
-----------
    state: unvalidated
    executable: None
    version: None
    port: None
    pid: None
    command: None

Since no image export operations have been performed yet, the orca server is not yet running.

Let's export this figure as an SVG image, and record the runtime.

In [4]:

%%time
import plotly.io as pio
from IPython.display import SVG, display
img_bytes = pio.to_image(fig, format="svg")
display(SVG(img_bytes))