Install¶

Requirements¶

macOS Apple Silicon only

vupai is macOS Apple-Silicon only: it depends on Apple MLX for on-device speech, plus two Homebrew binaries. It will not run on Linux or Intel Macs.

macOS on Apple Silicon (M-series), macOS 13.5+ (developed on macOS 26).
tmux and sox:
```
brew install tmux sox
```

Python ≥ 3.11 and uv, used to install the CLI:

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

Install from PyPI¶

After the Homebrew step above, install the vupai CLI from PyPI in its own isolated environment with uv:

uv tool install vupai

This puts vupai on your PATH. The Parakeet model (~0.6B, ~2 GB) downloads automatically on first transcription.

To upgrade later: uv tool upgrade vupai.

Note

Prefer the bleeding edge? Install straight from git instead: uv tool install git+https://github.com/itsjrsa/vupai.

From source (development)¶

git clone git@github.com:itsjrsa/vupai.git
cd vupai
uv sync            # creates .venv and installs everything (incl. the MLX runtime)

Run the CLI with uv run vupai … from the repo, or see the live-reload loop (vupai reload / vupai --reload) in AGENTS.md.

To install this checkout as a real vupai on your PATH (no PyPI), instead of uv run:

uv tool install .            # from the repo root; re-run after pulling changes

Note

The examples in these docs use the bare vupai command (the installed tool). If you're running from a source checkout, prefix each one with uv run (e.g. uv run vupai setup).

Contributing? See AGENTS.md.

Next: set up permissions, mic, and hotkeys.