Claude Code Setup

Requirements

• macOS 13+, Windows 10 1809+, Windows Server 2019+, Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+.
• At least 4 GB RAM and an x64 or ARM64 processor.
• Internet access and a supported Claude Code account or configured enterprise provider.
• Git for Windows is optional on native Windows, but enables the Bash tool; WSL 2 supports sandboxed execution.

Quick setup

Install, verify, and open a project

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

claude --version
claude doctor

cd path/to/your-project
claude

Step 1

Choose native Windows or WSL before installing

Install Claude Code in the same environment that owns your repository and toolchain. Mixing Windows Node, WSL paths, and Linux package managers creates avoidable PATH and permission errors.

1. Use native Windows for Windows-native repositories, PowerShell tools, and files stored under C:\.
2. Use WSL 2 for Linux toolchains, repositories stored under ~/code, or sandboxed command execution.
3. On macOS or Linux, install from the terminal where Git, your package manager, and project commands already work.

Step 2

Install and verify the executable

The native installer is Anthropic's recommended route and updates automatically. Verification should prove both that the executable is on PATH and that its configuration is healthy.

claude --version

claude doctor

Important: Do not run the Windows installer as Administrator. If you use npm instead, the current package requires Node.js 22+ and should not be installed with sudo.

Step 3

Authenticate from the environment you will use

Run `claude` and follow the browser login flow. Claude Code currently supports eligible Claude plans, Console accounts, and configured enterprise providers.

1. Start Claude Code from the project terminal, not from an unrelated home directory.
2. Complete the browser prompt and return to the same terminal.
3. If an ANTHROPIC_API_KEY is already set, confirm that you intended to use that key before approving it.

Step 4

Connect one repository and test context

Before asking for edits, verify that Claude can find the entry points, build commands, tests, and important boundaries of the repository.

1. Compare the explanation with the README, package scripts, and CI configuration.
2. Correct missing or wrong assumptions before generating CLAUDE.md.
3. Commit or stash existing work before allowing the first edit.

Explain this repository's entry points, test commands, and risky areas. Do not edit files.

Step 5

Add CLAUDE.md and narrow permissions

Repository instructions should contain real commands and boundaries, not a product description. Permission choices should match the task rather than remain permanently broad.

1. Document install, development, test, lint, and build commands that actually pass in the repository.
2. Name directories the agent may change and areas that require explicit approval.
3. Use plan mode or read-only exploration for broad or unfamiliar work before permitting edits.
4. Review the diff and rerun important checks outside the agent's own summary.

Step 6

Update without changing installation methods

Native installations update in the background. Package-manager installs use the update mechanism of that package manager.

claude update

winget upgrade Anthropic.ClaudeCode

brew upgrade claude-code

Common setup errors