Installation

Orca Framework is source-available. You install it from its GitHub repository, and pip fetches cheshire-drivers, the driver package it depends on, from GitHub too. You do not need any lab hardware: everything works in simulation.

This page installs Orca 2.0.0. The cheshire-orca 0.x packages on PyPI and the v1.0.0 tag in the orca repository are earlier AGPL-3.0 releases, documented in the Orca Legacy docs.

What you need

• Python 3.10 or higher. Check with python --version. If you are on an older version, python.org/downloads has the installer.
• pip, which usually comes with Python.
• Git. You clone Orca, and pip pulls two of its dependencies, cheshire-drivers and PyLabRobot, from git URLs rather than from PyPI.

Install

Create a virtual environment first, so Orca's dependencies stay separate from the rest of your system. Skip this if your project already has one.

python -m venv .venv

# Mac / Linux
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Your prompt usually shows (.venv) once the environment is active. Then clone Orca and install it:

git clone https://github.com/Cheshire-Labs/orca.git
cd orca
pip install -e .

That is the whole install.

pip installs cheshire-drivers from GitHub at the release this version of Orca pins. Use a dedicated virtual environment: cheshire-drivers installs a fork of PyLabRobot under the name pylabrobot, so it replaces any upstream PyLabRobot already in the environment.

Orca's own README installs -e ".[dev]" instead, because it is written for someone about to run the test suite. dev is the only extra Orca defines and it contains test tooling and nothing else: pytest, pytest-asyncio, pytest-timeout, pytest-xdist, types-setuptools and black. No part of Orca imports any of them, so pip install -e . is the right command for using Orca. If you later start working on Orca itself, rerun the install with the extra; see Test tooling.

Check it worked

orca version

You should see a version number. A ModuleNotFoundError or a PackageNotFoundError means the install did not complete, or your virtual environment is not active.

Advanced

You only need this if you are patching Orca's source or debugging an install.

Test tooling

pip install -e ".[dev]"

Run this in the same environment when you want to run Orca's tests. To run the suite, also clone orca-client beside orca: one test reads its source.

Changing cheshire-drivers too

Clone cheshire-drivers beside orca and run pip install -e ../cheshire-drivers after every other install, including pip install -e ".[dev]". Your clone replaces the copy pip fetched. Any later install of Orca fetches the pinned copy again and replaces your clone without a warning.

Read the version without the CLI

python -c "from importlib.metadata import version; print(version('cheshire-orca'))"

What comes with it

You do not import or configure any of these directly. Orca uses them under the hood.

• cheshire-drivers: the driver interfaces plus the simulation drivers behind every run mode that does not touch hardware. A direct dependency.
• PyLabRobot: instrument control and labware geometry, used by drivers to talk to real devices. It arrives through cheshire-drivers, from the Cheshire Labs fork, which is why the install needs Git.
• FastAPI and Uvicorn: the localhost daemon that exposes the runtime over REST and SSE.
• Typer and Rich: the orca CLI.
• SQLAlchemy and aiosqlite: the embedded SQLite stores for teachpoints, deck layouts, incidents, execution records, grip profiles and move defaults.
• NetworkX: the routing graph the runtime plans labware moves over.

See also

• Quick Start: run your first workflow in simulation.
• Architecture: the conceptual model, before you write code.
• CLI overview: what the orca command can do.
• PyLabRobot: how Orca uses it, and where labware definitions come from.