Skip to main content
Version: 2.0.0

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.