Install Spec Kitty on Linux
Who is this for (1)
- Stakeholder Persona: Project Owner — Written for the Project Owner reader.
Install the spec-kitty CLI on a Linux distribution using your preferred Python tooling.
The PyPI distribution is named
spec-kitty-cli; the binary it installs isspec-kitty.
Prerequisites
-
A modern Linux distribution (Ubuntu 22.04+, Debian 12+, Fedora 39+, Arch, etc.).
-
Python 3.11+. Verify:
Terminal window python3 --versionInstall Python 3.11+ if needed:
Terminal window # Ubuntu / Debiansudo apt update && sudo apt install -y python3.12 python3.12-venv# Fedorasudo dnf install -y python3.12# Archsudo pacman -S python -
On modern distros (Ubuntu 24.04, Debian 12, Fedora 39+) the system Python is “externally managed” per PEP 668. Use pipx or uv tool to avoid
--break-system-packages.
Method 1: pipx (recommended for global tool install)
# Ubuntu / Debiansudo apt install -y pipxpipx ensurepath
# Fedorasudo dnf install -y pipxpipx ensurepath
# Archsudo pacman -S python-pipxpipx ensurepathThen install Spec Kitty:
pipx install --pip-args=--pre spec-kitty-clispec-kitty --versionpipx installs spec-kitty into an isolated venv and exposes it on your PATH via ~/.local/bin.
Method 2: uv tool
# install uv (one-time)curl -LsSf https://astral.sh/uv/install.sh | sh
# install spec-kittyuv tool install --prerelease=allow spec-kitty-clispec-kitty --versionThe Astral installer places uv and its tool shims under ~/.local/bin (some older installers used ~/.cargo/bin). Ensure that directory is on your PATH.
Method 3: pip in a venv (contributor path)
python3 -m venv .venvsource .venv/bin/activatepip install --pre spec-kitty-clispec-kitty --versionspec-kitty is only available while the venv is activated. Run deactivate to leave.
Do not
sudo pip install spec-kitty-cliagainst system Python on Ubuntu 24.04 / Debian 12 / Fedora — modern distros block this withexternally-managed-environment. Use pipx or uv instead.
Verification
spec-kitty --version# spec-kitty-cli version 4.0.0rc8Useful follow-ups:
spec-kitty --helpspec-kitty doctor # post-install health check (in an initialized project)PATH considerations on Linux
pipx and uv tool install shims under ~/.local/bin. If spec-kitty is “command not found”, that directory is not on your PATH.
bash:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrcexec bash -lzsh:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrcexec zshfish:
fish_add_path ~/.local/binpipx ensurepath will patch your rc file automatically if you skipped this.
If uv is in ~/.cargo/bin instead of ~/.local/bin, add that path too.
Troubleshooting
externally-managed-environment from pip — Your distro forbids pip install against system Python (PEP 668). Switch to pipx or a venv. Do not use --break-system-packages.
spec-kitty: command not found — ~/.local/bin (or ~/.cargo/bin) is not on your PATH. Re-run pipx ensurepath, restart your shell, then which spec-kitty.
SSL: CERTIFICATE_VERIFY_FAILED — Usually means an outdated ca-certificates package. sudo apt install --reinstall ca-certificates (Debian/Ubuntu) or the equivalent for your distro.
Old Python on enterprise Linux (RHEL 8, CentOS 7) — System Python is too old. Install Python 3.11+ from your distro’s modules or from python.org source, then pipx install --python /path/to/python3.11 spec-kitty-cli.