Skip to main content

Installation

Preview: not yet released

Orca Framework has not been released yet, so there is no public install. Access to the preview package is by request for evaluation. Contact us to get set up.

Orca Framework is a Python package named cheshire-orca. It is not on public PyPI, so you install it from the private package index in your access email. You do not need any lab hardware: everything works in simulation.

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 need it even for a package install: one of Orca's dependencies, PyLabRobot, is pulled from a git URL rather than from PyPI.
  • Your access email. Contact us for one. It carries the private package index (or wheel) and the source repository URLs.

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 install:

pip install cheshire-orca --index-url <private-index-url-from-your-access-email>

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 reading or patching Orca's source, or debugging an install.

Install from source​

Two repositories, not one. cheshire-drivers is a separate package that Orca depends on and it is not on PyPI, so install it first, from a checkout beside Orca's. This is the layout CI uses.

git clone <drivers-repo-url-from-your-access-email> cheshire-drivers
git clone <orca-repo-url-from-your-access-email> orca
cd orca
pip install -e ../cheshire-drivers
pip install -e .

Add the dev extra (pip install -e ".[dev]") if you want the test tooling: pytest, pytest-asyncio, pytest-timeout, pytest-xdist and black. It is the only extra the package defines.

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.