Skip to content

Installation

Install erk and verify your setup.

Prerequisites: Complete Prerequisites first—you need Python 3.11+, Claude Code, uv, and GitHub CLI.

Install erk

Install erk as a project dependency:

cd your-project
uv add erk
uv sync

Verify the installation:

# In your project directory (with venv activated)
erk --version

You should see output like erk 0.4.x.

Troubleshooting:

  • uv: command not found — Install uv first. See Prerequisites.
  • Python version error — erk requires Python 3.11 or higher. Check with python --version.
  • erk: command not found — Make sure your venv is activated (. .venv/bin/activate) or use .venv/bin/erk directly.

Verify Installation

Run the doctor command to check your setup:

erk doctor

Doctor checks two categories:

  • Repository Setup: Checks specific to the current repo (git, config, hooks)
  • User Setup: Global prerequisites (CLI tools, authentication)

Condensed output (default):

🔍 Checking erk setup...

Repository Setup
✅ Git repository (2 checks)
✅ Claude settings (4 checks)
✅ Erk configuration (6 checks)
✅ GitHub (3 checks)
✅ Hooks (1 checks)

User Setup
✅ erk CLI installed: v0.4.7
✅ Claude CLI installed
✅ GitHub CLI installed
✅ uv installed
✅ User checks (4 checks)

✨ All checks passed!

Verbose output (erk doctor --verbose):

Add --verbose to see individual checks within each category—useful for debugging failures.

Status indicators:

Icon Meaning Action
✅ Passed None needed
ℹ️ Info Optional enhancement available
❌ Failed Fix required before continuing

If checks fail:

  • Repository Setup failures — Run erk init to configure the repo
  • User Setup failures — See Prerequisites to install missing tools

Initialize a Repository

Erk initialization has two phases:

  1. Project setup (one-time per repository) — Creates configuration files and Claude Code artifacts that are committed to the repo. Once done, other team members get erk support automatically.

  2. User setup (one-time per developer) — Creates local configuration on each developer's machine. This includes the global config file.

Run init from your project's root directory:

erk init

What happens during project setup

When you run erk init in a repository for the first time, it creates:

  • .erk/config.toml — Repository configuration (commit this)
  • .erk/required-erk-uv-tool-version — Minimum erk version for the project
  • .claude/commands/erk/ — Claude Code slash commands like /erk:plan-save
  • .claude/skills/ — Coding standards and documentation patterns
  • .claude/agents/ — Agent definitions (e.g., devrun for test execution)

Once committed, any developer who clones the repo gets these artifacts automatically.

What happens during user setup

Each developer needs local state that isn't committed:

  • ~/.erk/config.json — Global config with:
  • erk_root: Where worktrees are created (default: ~/.erk/repos/<repo>/worktrees/)
  • use_graphite: Auto-detected based on whether gt is installed

The first time you run erk init (in any repo), it creates your global config. Subsequent runs in other repos skip this step.

For optional capabilities (devrun, dignified-python, etc.), init flags, and troubleshooting, see Advanced Configuration.

Quick Reference

Task Command
Install erk uv add erk && uv sync
Check version erk --version
Verify setup erk doctor
Verbose diagnostics erk doctor --verbose
Initialize repo erk init
Update erk uv upgrade erk

Next Steps