opentrons-dev-setup

name: opentrons-dev-setup description: > Guide users through setting up a local development environment for the Opentrons opentrons/opentrons monorepo. Use this skill whenever a user mentions setting up Opentrons development, cloning the Opentrons repo, installing dev dependencies for Opentrons, getting started contributing to Opentrons, or hits errors during Opentrons dev setup (pyenv, uv, nvs, yarn, Node.js, Python, make setup, brew, git). Also trigger when the user seems new to the terminal or CLI and is trying to run Opentrons software locally. Trigger even if the user just says "I want to contribute to Opentrons", "how do I get the Opentrons repo running locally", or "I'm stuck on the Opentrons setup."

Opentrons Dev Environment Setup Skill

This skill helps users — including those new to the command line — set up their local development environment for the Opentrons monorepo.

Guiding Principles

• Be patient and explicit. Users may be unfamiliar with the terminal. Explain what each command does before showing it.
• One step at a time. Always ask the user to run the verification command and share the output before moving on.
• Explain tool concepts briefly. When introducing a new tool (pyenv, uv, nvs, etc.), give a one-sentence explanation of what it is and why it's needed.
• Watch for shell/PATH issues. The most common source of problems. Remind users to restart their terminal after installs.
• If the user pastes an error, diagnose it using the Troubleshooting section below.

Required Tools and Versions

Step 0: Identify the User's Setup

Before anything else, find out:

1. Which OS? macOS, Linux, or Windows
2. Mac users: Apple Silicon (M1/M2/M3/M4) or Intel? (Apple menu → About This Mac)
3. New to the terminal? If so, explain: "The terminal is a text-based way to control your computer. You type commands and press Enter to run them."

Then follow the appropriate OS section below.

macOS Setup

What is a shell config file?

macOS uses ~/.zprofile (runs at login) and ~/.zshrc (runs each time you open a terminal) to set up your environment. Several steps below add lines to these files — this is normal.

Step 1: Homebrew (macOS package manager)

What it is: Homebrew is like an app store for developer tools. It lets you install things like git with a single command.

1. Go to https://brew.sh and copy the install command shown on the page.

2. Paste it in your terminal and press Enter. It takes a few minutes.

3. Critical: When it finishes, Homebrew prints a "Next steps" section. You must run those two commands or Homebrew won't work. They look like:

   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
   eval "$(/opt/homebrew/bin/brew shellenv)"
   

4. Close and reopen your terminal, then verify:

   brew --version
   

   ✅ Expected: Homebrew 4.x.x

5. Install git:

   brew install git
   git --version
   

   ✅ Expected: git version 2.x.x

Step 2: Node.js via nvs

What it is: Node.js lets you run JavaScript on your computer. nvs (Node Version Switcher) ensures the correct version of Node.js is active — Opentrons needs a specific version.

export NVS_HOME="$HOME/.nvs"
git clone https://github.com/jasongin/nvs "$NVS_HOME"
. "$NVS_HOME/nvs.sh" install

Close and reopen your terminal, then:

nvs --version
nvs add 22.22.0
nvs auto on
nvs link 22.22.0
node --version

✅ Expected: v22.22.0

To make v22.22.0 the default every time a new terminal opens, run:

nvs link 22.22.0

If nvs isn't found after reopening the terminal, check that ~/.zshrc contains:

export NVS_HOME="$HOME/.nvs"
[ -s "$NVS_HOME/nvs.sh" ] && . "$NVS_HOME/nvs.sh"

Step 3: Python via pyenv

What it is: Python is the language the robot software is written in. pyenv lets you install and switch Python versions — Opentrons needs exactly 3.12.12.

⚠️ Do NOT install pyenv using brew install pyenv. Use the method below. The Homebrew version is unreliable, especially on Apple Silicon Macs.

git clone https://github.com/pyenv/pyenv.git ~/.pyenv
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

Close and reopen your terminal, then:

pyenv --version
pyenv install 3.12.12
python --version

✅ Expected: Python 3.12.12

🍎 Apple Silicon only: If python --version shows the wrong version, run:

eval "$(pyenv init --path)"
pyenv local 3.12.12
python --version

Step 4: uv (Python package installer)

What it is: uv installs Python libraries. Opentrons uses it instead of the built-in pip because it's faster and more reliable.

curl -LsSf https://astral.sh/uv/install.sh | sh

Close and reopen your terminal, then:

uv --version

✅ Expected: uv 0.x.x

If uv is not found:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
uv --version

Step 5: Apple Silicon only — jpeg-turbo

Required for a hardware library called Pillow:

brew install jpeg-turbo

Linux Setup (Ubuntu/Debian)

These steps assume Ubuntu or a Debian-based distro using Bash. For other distros, adapt the package manager commands accordingly.

Step 1: General dependencies

sudo apt-get update
sudo apt-get install -y make git curl ssh build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev libncursesw5-dev xz-utils \
  tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

These are required for pyenv to build Python from source. Verify:

git --version

✅ Expected: git version 2.x.x

Step 2: Node.js via nvs

export NVS_HOME="$HOME/.nvs"
git clone https://github.com/jasongin/nvs "$NVS_HOME"
. "$NVS_HOME/nvs.sh" install

Close and reopen terminal, then:

nvs --version
nvs add 22.22.0
nvs auto on
node --version

✅ Expected: v22.22.0

If nvs isn't found, add to ~/.bashrc:

echo 'export NVS_HOME="$HOME/.nvs"' >> ~/.bashrc
echo '[ -s "$NVS_HOME/nvs.sh" ] && . "$NVS_HOME/nvs.sh"' >> ~/.bashrc
source ~/.bashrc

Step 3: Python via pyenv

git clone https://github.com/pyenv/pyenv.git ~/.pyenv
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init --path)"' >> ~/.profile
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

Close and reopen terminal, then:

pyenv --version
pyenv install 3.12.12
python --version

✅ Expected: Python 3.12.12

Step 4: uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Close and reopen terminal, then:

uv --version

If not found:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
uv --version

Cloning the Repo and Running Setup (macOS + Linux)

Once all system tools are installed:

Clone the repository

What this does: Downloads the Opentrons source code to your computer.

git clone https://github.com/Opentrons/opentrons.git
cd opentrons

Set the Python version for this project

pyenv local 3.12.12
python --version

✅ Expected: Python 3.12.12

Install yarn

What it is: Yarn installs the JavaScript packages the app depends on.

npm install --global yarn@1
yarn --version

✅ Expected: 1.x.x

Run the full setup

What this does: Downloads and installs all development dependencies. Creates Python virtual environments automatically using uv. This takes several minutes (5–15 min) — that is completely normal.

make setup

When complete with no red errors: you're ready to develop! 🎉

Final Verification Checklist

Run each command and confirm the version shown matches expectations:

node --version    # ✅ v22.22.0+
python --version  # ✅ Python 3.12.12
uv --version      # ✅ uv 0.x.x (any version)
yarn --version    # ✅ v1.22.19+ 
git --version     # ✅ git version 2.x.x

Also confirm make setup finished without any error messages in red.

Troubleshooting Guide

When a user reports an error, use this table first.

Diagnosing PATH issues

If a tool was installed but isn't found, ask the user to run:

echo $PATH

Look for the tool's directory in the output:

• Homebrew (Apple Silicon): /opt/homebrew/bin
• Homebrew (Intel): /usr/local/bin
• uv: $HOME/.local/bin
• pyenv: $HOME/.pyenv/bin
• nvs: $HOME/.nvs

If missing, add the export PATH=... line to their shell config file and source it.

Checking shell config files

# macOS
cat ~/.zprofile
cat ~/.zshrc

# Linux
cat ~/.profile
cat ~/.bashrc

Tips for Helping CLI-Unfamiliar Users

• ~ means home folder — e.g., /Users/yourname on Mac, /home/yourname on Linux.
• >> is safe — it appends a line to a file. Reassure users it won't overwrite anything.
• source reloads the shell config without closing the terminal. Useful shortcut.
• Encourage copy-paste for long commands — typing them by hand causes typos.
• Normalize errors — errors during setup are common and fixable. Stay calm and diagnostic.
• make setup takes time — warn users before they run it so they don't think it's frozen.