Install Optics

Optics has two parts. The core is the optics command, which reads your tests and runs them. Engines are optional add-ons: a driver for each kind of target (browser, phone, TV) and extra ways to find things on screen. You install the core once and add engines as you need them.

Before you begin#

You need Python 3.12 or newer. Check with:

$ python3 --version
Python 3.12.13

If you have an older version, install a current one from python.org or your system's package manager.

Install the core#

We recommend the installer. It creates a private Python environment under ~/.optics, adds optics to your PATH, and leaves your system Python alone.

$ curl -fsSL https://optics-framework.org/install | sh

PS> irm https://optics-framework.org/install.ps1 | iex

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install optics-framework

Open a new terminal so it picks up the updated PATH, then check the install:

$ optics --version
Optics Framework 1.10.5

$ curl -fsSL https://optics-framework.org/install | sh -s -- --extra playwright,easyocr

Add engines for your platform#

The core install ships without drivers, so it stays small. Add the ones for what you test. optics setup installs engines that match your Optics version:

$ optics setup --install playwright

$ optics setup --install appium

$ optics setup --install appium

Run optics setup with no options to pick engines from a list instead, or optics setup --list to see every name.

Optional engines#

Add these when a page tells you to. You don't need them for your first test.

Bundles install several at once: mobile (Appium), web (Playwright and Selenium), vision (all OCR engines) and all (everything except the MCP server). The engines reference lists every engine.

Check your setup#

optics doctor checks Python, each engine, and the tools around them:

$ optics doctor

🩺 optics doctor

Core
  ✅ python                            3.12.13
  ✅ optics-framework                  installed, version 1.10.5

Engines
  ⚠️ Appium                            appium-python-client not installed
      → optics setup --install appium
  ✅ Playwright                        playwright 1.63.0

Web
  ✅ playwright browser                Chromium download found

✅ rows are ready. ⚠️ rows are optional or not needed for your platform. Pass a project folder (optics doctor my_project) to also check its config.yaml.

If the install doesn't work#

• **optics: command not found.** Open a new terminal. If it still fails, add ~/.optics/bin to your PATH, as the installer printed.
• **optics setup refuses to install.** Conda, pipx and tool-managed environments (uv tool, Poetry, PDM) manage their own packages, so optics setup prints the right command for that tool instead. Run that command, or use a plain virtual environment.
• EasyOCR fails under Conda. EasyOCR and Optics need different NumPy versions under Conda. Use the installer or a standard venv.

Troubleshooting covers more cases.

Next steps#