From b278d66b2c9b7a695186be0aa52ceb5feac65120 Mon Sep 17 00:00:00 2001 From: sha0dow <85430783+D7x7z49@users.noreply.github.com> Date: Thu, 23 Apr 2026 21:12:17 +0800 Subject: [PATCH] docs(install): add pipx as alternative installation method (#2288) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(install): add pipx as alternative installation method - Add pipx commands to README.md installation section - Add note about pipx compatibility to docs/installation.md - Mention pipx persistent installation in docs/quickstart.md - Add pipx upgrade instructions to docs/upgrade.md - Clarify that project has no uv-specific dependencies Refs: https://github.com/github/spec-kit/discussions/2255 * docs(install): address Copilot feedback - update prerequisites and upgrade references for pipx * Update docs/quickstart.md markdownlint’s MD012 (enabled in this repo) flags multiple consecutive blank lines Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/upgrade.md In the Quick Reference table, the label “pipx upgrade” is misleading because the command shown is `pipx install --force ...` (a reinstall). by copilot. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 7 ++++++- docs/installation.md | 9 ++++++++- docs/quickstart.md | 11 +++++++++++ docs/upgrade.md | 9 +++++++++ 4 files changed, 34 insertions(+), 2 deletions(-) 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/spec-kit.git@vX.Y.Z +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/spec-kit.git@vX.Y.Z +# pipx users: pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z ``` #### 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/spec-kit.git@vX.Y.Z specify init ``` +> [!NOTE] +> For a persistent installation, `pipx` works equally well: +> ```bash +> pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z +> ``` +> 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 [!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 +> 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/spec-kit.git@vX.Y.Z` | Get latest CLI features without touching project files | +| **CLI Tool Only (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Reinstall/upgrade a pipx-installed CLI to a specific release | | **Project Files** | `specify init --here --force --ai ` | 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/spec-kit.git@vX.Y.Z specify init --here --ai copilot ``` +### If you installed with `pipx` + +Upgrade to a specific release: + +```bash +pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z +``` + ### Verify the upgrade ```bash