Install Spec Kitty on macOS
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Install the spec-kitty CLI on macOS using your preferred Python tooling. Three install methods are covered; pick one.
The PyPI distribution is named
spec-kitty-cli; the binary it installs isspec-kitty.
Prerequisites
-
macOS 12 (Monterey) or newer.
-
Python 3.11+. Verify with:
Terminal window python3 --versionIf you see
Python 3.10.xor older, install a newer Python:Terminal window Or use pyenv / the official installer.
-
Optional but recommended: Homebrew for installing
pipxoruv.
Method 1: pipx (recommended for global tool install)
pipx installs each Python application into its own isolated virtual environment and exposes its console scripts on your PATH. This is the safest default on a Mac where the system Python is managed by Apple or Homebrew.
brew install pipxpipx ensurepathpipx install --pip-args=--pre spec-kitty-cliOpen a new shell so the PATH change takes effect, then verify:
spec-kitty --version# spec-kitty-cli version 4.0.0rc8Method 2: uv tool
uv installs Python tools into per-tool venvs similarly to pipx, but faster.
brew install uvuv tool install --prerelease=allow spec-kitty-clispec-kitty --versionIf uv was installed via the Astral installer instead of Homebrew, its binary directory may be ~/.cargo/bin or ~/.local/bin. Make sure that directory is on your PATH (see below).
Method 3: pip in a venv (contributor path)
Use this only when you are intentionally managing the Python environment yourself (for example, inside a clone of the spec-kitty repository).
python3 -m venv .venvsource .venv/bin/activatepip install --pre spec-kitty-clispec-kitty --versionspec-kitty is only on your PATH while the venv is activated. Deactivate with deactivate.
Direct
pip install spec-kitty-cliagainst a system Python on macOS may succeed today but is not recommended — Homebrew Python and Apple Python both treat themselves as externally managed environments. Prefer pipx or uv tool.
Verification
Regardless of method, the verification step is identical:
spec-kitty --versionYou should see output similar to:
spec-kitty-cli version 4.0.0rc8Then probe further:
spec-kitty --helpspec-kitty doctor # post-install health check (in an initialized project)PATH considerations on macOS
Both pipx and uv tool install the spec-kitty script under ~/.local/bin by default. If spec-kitty is “command not found” after install, your shell PATH is the problem.
zsh (default on macOS 10.15+):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcexec zshbash:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profileexec bash -lIf you installed uv via the Astral installer, you may also need ~/.cargo/bin on your PATH; the installer prints the exact line to add.
To make pipx itself update PATH for you the first time:
pipx ensurepathTroubleshooting
spec-kitty: command not found — Your shell cannot see the install directory. Re-run pipx ensurepath (or add ~/.local/bin to PATH as shown above) and open a new terminal.
SSL: CERTIFICATE_VERIFY_FAILED during install — Usually means an old Python install. Use python3 --version to confirm you have 3.11+ and reinstall Python from python.org or Homebrew so the bundled certificates are current.
externally-managed-environment error from pip — You ran pip install against system Python. Switch to pipx or create a venv first.
Apple Silicon vs Intel — spec-kitty-cli is pure Python, so the same wheel works on both architectures. If pip builds from source, ensure Xcode command-line tools are installed: xcode-select --install.