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

Installation

Important

The only official, maintained packages for Spec Kit come from the github/spec-kit GitHub repository. Any packages with the same name available on PyPI (e.g. specify-cli on pypi.org) are not affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.

Persistent Installation (Recommended)

Install once and use everywhere. Replace vX.Y.Z with a tag from Releases:

Note

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

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.

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

The .specify/scripts directory will contain both .sh and .ps1 scripts.

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.