Install the Imperal SDK

Use Homebrew for a clean, isolated install:

brew install python@3.12
python3.12 --version
# Python 3.12.x

If you don't have Homebrew, install it first.

Ubuntu / Debian:

sudo apt update && sudo apt install -y python3.12 python3.12-venv python3-pip
python3.12 --version

Arch:

sudo pacman -S python python-pip

Other distros: check your package manager or use pyenv for version flexibility.

Strongly recommended: use WSL2 and follow the Linux instructions inside it.

If you must use native Windows, install Python from python.org and ensure "Add Python to PATH" is checked.

mkdir my-extension && cd my-extension
python3.12 -m venv .venv
source .venv/bin/activate         # macOS/Linux
# .venv\Scripts\activate          # Windows native
pip install --upgrade pip

Your shell prompt should now show (.venv).

uv is a Rust-based pip replacement. ~10× faster.

# Install uv (one-time)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Per project:
mkdir my-extension && cd my-extension
uv venv --python 3.12
source .venv/bin/activate

Use uv pip install ... everywhere instead of pip install ....

Install:

• Python (Microsoft) — language server
• Pylance — type checking + autocomplete (Pydantic models work great)
• Ruff (Astral) — linting and formatting

Open your extension folder. VS Code prompts to select the interpreter — pick .venv/bin/python.

Open the extension folder as a project. PyCharm auto-detects .venv and offers to use it as the interpreter — accept.

For Pydantic strict checking: Settings → Editor → Inspections → Python → Type checker → strict.

Install pyright language server and configure it via your LSP plugin (coc-pyright, mason-lspconfig, etc).

pip install pyright