github-spec-kit/docs/installation.md

Installation Guide

Prerequisites

• Linux/macOS (or Windows; PowerShell scripts now supported without WSL)
• AI coding agent: Claude Code, GitHub Copilot, Codebuddy CLI, Gemini CLI, or Pi Coding Agent
• uv for package management (recommended) or pipx for persistent installation
• Python 3.11+
• Git (optional — required only when the git extension is enabled)

Installation

Note

The official specify-cli package is published to PyPI by the github/spec-kit maintainers. PyPI publishing is performed after each GitHub release and may lag briefly. Source installs from the GitHub repository are always available immediately.

Persistent Installation (Recommended)

Install once and use everywhere:

Note

The command below requires uv. If you see command not found: uv, install uv first.

uv tool install specify-cli@latest

Or install from source using a specific release tag:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Then initialize a project:

specify init <PROJECT_NAME> --integration copilot

One-time Usage

Run directly without installing — see the One-time usage (uvx) guide.

Alternative Package Managers

• pipx — see the pipx installation guide
• Enterprise / Air-Gapped — see the air-gapped installation guide

Specify Integration

Interactive terminals prompt you to choose a coding agent integration during initialization. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot unless you pass --integration.

You can proactively specify your coding agent integration during initialization:

specify init <project_name> --integration claude
specify init <project_name> --integration gemini
specify init <project_name> --integration copilot
specify init <project_name> --integration codebuddy
specify init <project_name> --integration pi

Specify Script Type (Shell vs PowerShell)

All automation scripts now have both Bash (.sh) and PowerShell (.ps1) variants.

Auto behavior:

• Windows default: ps
• Other OS default: sh
• Interactive mode: you'll be prompted unless you pass --script

Force a specific script type:

specify init <project_name> --script sh
specify init <project_name> --script ps

Ignore Agent Tools Check

If you prefer to get the templates without checking for the right tools:

specify init <project_name> --integration claude --ignore-agent-tools

Verification

After installation, run the following command to confirm the correct version is installed:

specify version

This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.

Stay current: Run specify self check periodically to learn whether a newer release is available — it is read-only and never modifies your installation. When you are ready to upgrade, follow the Upgrade Guide.

After initialization, you should see the following commands available in your coding agent:

• /speckit.specify - Create specifications
• /speckit.plan - Generate implementation plans
• /speckit.tasks - Break down into actionable tasks

Scripts are installed into a variant subdirectory matching the chosen script type:

• .specify/scripts/bash/ — contains .sh scripts (default on Linux/macOS)
• .specify/scripts/powershell/ — contains .ps1 scripts (default on Windows)

Troubleshooting

Enterprise / Air-Gapped Installation

If your environment blocks access to PyPI or GitHub, see the Enterprise / Air-Gapped Installation guide for step-by-step instructions on creating portable wheel bundles.

Git Credential Manager on Linux

If you're having issues with Git authentication on Linux, see the Air-Gapped Installation guide for Git Credential Manager setup instructions.