Claude Code
Complete Setup Guide — Windows · macOS · Linux · VS Code
System Requirements at a Glance
Platform Min OS Notes
Windows Windows 10 (build 1809)+ Git for Windows required
macOS macOS 13 Ventura+ Intel & Apple Silicon
Linux Ubuntu 20.04+ / Debian 12+ curl + bash in terminal
VS Code VS Code 1.85+ Extension from Marketplace
Prerequisites
Before installing Claude Code you need a paid Anthropic account. The free tier does not include CLI
access. Choose one of:
• Claude Pro — $20/month. Sufficient for most developers.
• Claude Max — $100–200/month. Higher rate limits for heavy use.
• Anthropic Console — Pay-per-token via API key. Ideal for CI/CD pipelines.
Note: The native installer (recommended) requires NO [Link]. [Link] 18+ is only needed if you use the
legacy npm install method.
Windows Setup
Step 1 — Install Git for Windows
Git for Windows is mandatory — the Claude Code installer will fail without it.
• Download from [Link]/download/win and run with default settings.
• Restart your terminal after installation so Git is on your PATH.
Step 2 — Install Claude Code (Option A — PowerShell)
Open PowerShell (not CMD, not Git Bash) and run:
irm [Link] | iex
Step 2 — Install Claude Code (Option B — CMD)
curl -fsSL [Link] -o [Link] && bash [Link]
Step 3 — Verify Installation
claude --version
If the command is not found, close and reopen your terminal to refresh PATH.
Step 4 — Authenticate
claude
On first launch a browser window opens. Sign in with your Anthropic account.
Option C — WSL (Windows Subsystem for Linux)
If you prefer a Linux environment on Windows, install WSL first:
wsl --install -d Ubuntu
Then open your Ubuntu terminal and follow the Linux instructions below.
Note: Install Claude Code inside WSL using the Linux curl command, not the PowerShell installer.
macOS Setup
Step 1 — Open Terminal
Press Cmd+Space, type Terminal, and press Enter. Any terminal app (iTerm2, Warp, etc.) works fine.
Step 2 — Install Claude Code (Recommended — Native Installer)
curl -fsSL [Link] | bash
After installation, source your shell config or open a new terminal:
source ~/.zshrc
Step 2 — Alternative: Homebrew
brew install claude-code
Note: Homebrew does NOT auto-update. Run 'brew upgrade claude-code' manually for updates.
Step 3 — Verify
claude --version
Step 4 — Authenticate
claude
A browser window opens for OAuth login. Sign in with your Anthropic account.
Linux Setup
Supported distributions include Ubuntu 20.04+, Debian 12+, and most major distros. Alpine Linux requires
additional packages (see below).
Step 1 — Install Claude Code
curl -fsSL [Link] | bash
Step 2 — Update PATH
If claude is not found after installation, add it to your PATH:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Step 3 — Verify
claude --version
Step 4 — Authenticate
claude
Complete OAuth login in the browser, or set an API key:
export ANTHROPIC_API_KEY="sk-ant-..."
Alpine Linux (musl-based distros)
Install required dependencies first:
apk add libgcc libstdc++ ripgrep
USE_BUILTIN_RIPGREP=0 curl -fsSL [Link] | bash
VS Code Integration
Step 1 — Open Extensions View
Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (macOS). Search for Claude Code and install the
extension published by Anthropic.
Step 2 — Open Claude Code Panel
Use the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and type Claude Code: Open. Alternatively click
the Spark icon in the top-right corner of the editor or the Claude Code label in the bottom status bar.
Extension Features
• Inline diff review with Accept / Reject buttons
• @-mentions for context-aware file references
• Plan Mode — review Claude's plan before execution
• Conversation history panel
• Model selector in the Settings UI under the 'Claude Code' section
Using the Integrated Terminal (Advanced)
Press Ctrl+` to open VS Code's integrated terminal and run claude directly. This exposes all CLI flags and
enables scripting / piping, at the cost of losing the GUI diff panel.
Windows Users — VS Code + WSL
If you are using WSL, connect VS Code to your WSL environment:
• Install the Remote - WSL extension in VS Code.
• Open a WSL terminal and navigate to your project folder.
code .
VS Code will reopen connected to WSL, where Claude Code is installed.
Post-Installation: Essential Configuration
Create a [Link] File (Recommended)
[Link] tells Claude Code about your project conventions, stack, and rules. Place it in your project
root:
# Project: My App # Stack: TypeScript, React, Postgres
# Conventions: ESLint strict, no default exports # Test command: npm test
Configure .claudeignore
Similar to .gitignore — exclude files you don't want Claude to read:
.env .env.* node_modules/ build/ dist/ *.lock
Verify Everything Works
cd my-project claude
Try a simple task: "Explain what this file does" to confirm the full pipeline works.
Troubleshooting Quick Reference
Problem Fix
'claude' not found after install Close and reopen terminal to refresh PATH
Permission errors (Linux) Don't use sudo. Set a user-level npm prefix instead
Windows installer fails Ensure Git for Windows is installed first
Git Bash on Windows issues Use PowerShell or CMD, not Git Bash
Old macOS (pre-Ventura) Upgrade to macOS 13+ or use Docker-based Linux
Rate limit errors Consider upgrading to Claude Max plan
Alpine Linux failures Install libgcc, libstdc++, ripgrep via apk first
Official documentation: [Link]/en/docs/claude-code/overview · Support: [Link]
Generated March 2026 · Information current as of Claude Code native installer release