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. Source installs from the GitHub repository are also supported.

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

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.