Skip to content

💫 Toolkit to help you get started with SDD or any other process!

docs(install): add pipx as alternative installation method (#2288)

sha0dowb278d66b2c9b
diff --git a/README.md b/README.md
index b652aa361..88332922d 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,10 @@ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX
# Or install latest from main (may include unreleased changes)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+
+# Alternative: using pipx (also works)
+pipx install git+https://github.com/github/[email protected]
+pipx install git+https://github.com/github/spec-kit.git
```
Then verify the correct version is installed:
@@ -89,6 +93,7 @@ To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed inst
```bash
uv tool install specify-cli --force --from git+https://github.com/github/[email protected]
+# pipx users: pipx install --force git+https://github.com/github/[email protected]
```
#### Option 2: One-time Usage
@@ -426,7 +431,7 @@ Our research and experimentation focus on:
- **Linux/macOS/Windows**
- [Supported](#-supported-ai-coding-agent-integrations) AI coding agent.
-- [uv](https://docs.astral.sh/uv/) for package management
+- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
- [Python 3.11+](https://www.python.org/downloads/)
- [Git](https://git-scm.com/downloads)
diff --git a/docs/installation.md b/docs/installation.md
index ed253902a..c99810f70 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -4,7 +4,7 @@
- **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Pi Coding Agent](https://pi.dev)
-- [uv](https://docs.astral.sh/uv/) for package management
+- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pypa.github.io/pipx/) for persistent installation
- [Python 3.11+](https://www.python.org/downloads/)
- [Git](https://git-scm.com/downloads)
@@ -24,6 +24,13 @@ uvx --from git+https://github.com/github/[email protected] specify init <PROJE
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
```
+> [!NOTE]
+> For a persistent installation, `pipx` works equally well:
+> ```bash
+> pipx install git+https://github.com/github/[email protected]
+> ```
+> The project uses a standard `hatchling` build backend and has no uv-specific dependencies.
+
Or initialize in the current directory:
```bash
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 4b2c3c880..5c0f00930 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -22,6 +22,17 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
uvx --from git+https://github.com/github/spec-kit.git specify init .
```
+> [!NOTE]
+> You can also install the CLI persistently with `pipx`:
+> ```bash
+> pipx install git+https://github.com/github/spec-kit.git
+> ```
+> After installing with `pipx`, run `specify` directly instead of `uvx --from ... specify`, for example:
+> ```bash
+> specify init <PROJECT_NAME>
+> specify init .
+> ```
+
Pick script type explicitly (optional):
```bash
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 16f4b4b0c..934be675e 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -9,6 +9,7 @@
| What to Upgrade | Command | When to Use |
|----------------|---------|-------------|
| **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/[email protected]` | Get latest CLI features without touching project files |
+| **CLI Tool Only (pipx)** | `pipx install --force git+https://github.com/github/[email protected]` | Reinstall/upgrade a pipx-installed CLI to a specific release |
| **Project Files** | `specify init --here --force --ai <your-agent>` | Update slash commands, templates, and scripts in your project |
| **Both** | Run CLI upgrade, then project update | Recommended for major version updates |
@@ -34,6 +35,14 @@ Specify the desired release tag:
uvx --from git+https://github.com/github/[email protected] specify init --here --ai copilot
```
+### If you installed with `pipx`
+
+Upgrade to a specific release:
+
+```bash
+pipx install --force git+https://github.com/github/[email protected]
+```
+
### Verify the upgrade
```bash