How to Install Claude Code: Complete Setup Guide for Every Platform

Requirements

Before you install, make sure you have:

• Operating system: macOS, Linux, or Windows 10+
• RAM: 4 GB minimum, 8 GB recommended
• Terminal: Bash, Zsh, PowerShell, or CMD
• Account: Claude Pro, Max, Teams, Enterprise, or Anthropic Console with API credits

The free Claude.ai plan does not include Claude Code. You need a paid account.

Native Installer (Recommended)

The native installer is the fastest path. No Node.js required, no dependency management. It auto-updates in the background.

macOS and Linux

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

This downloads the binary, installs it to your system, and adds claude to your PATH. Open a new terminal window after installation so your shell picks up the new PATH entry.

Windows

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

Run this in PowerShell (not CMD). It installs the native binary and makes the claude command available globally.

Homebrew (macOS and Linux)

If you prefer managing tools through Homebrew:

brew install --cask claude-code

One caveat: Homebrew installations do not auto-update. You need to run brew upgrade claude-code manually to get new versions.

brew upgrade claude-code

npm Installation (Legacy)

The npm method still works but is no longer the recommended approach. Use this if you need to pin a specific version or work in an environment where npm is the standard package manager.

npm install -g @anthropic-ai/claude-code

This requires Node.js 18.0+ and npm. If you see EACCES permission errors, do not use sudo. Fix your npm permissions instead:

# Option 1: Change npm's default directory
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):
# export PATH=~/.npm-global/bin:$PATH

# Option 2: Use nvm (recommended)
# nvm manages Node versions and avoids permission issues entirely
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
nvm use 22
npm install -g @anthropic-ai/claude-code

Windows Installation Details

Windows users have two paths:

Option 1: Native PowerShell Installer

The simplest method. Open PowerShell and run:

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

Option 2: WSL (Windows Subsystem for Linux)

If you prefer a Linux environment, install WSL first, then use the Linux installation method inside it:

# Step 1: Install WSL (in PowerShell as admin)
wsl --install

# Step 2: After reboot, open your WSL terminal
# Step 3: Install Claude Code using the Linux method
curl -fsSL https://claude.ai/install.sh | bash

A common mistake: having Node.js installed on Windows but not inside WSL. If you use the npm method through WSL, you need Node.js installed inside the WSL environment, not just on the Windows side.

Authentication

After installation, run claude in any directory. On first launch, it opens your browser for OAuth authentication.

# Navigate to your project
cd your-project

# Start Claude Code
claude

# Follow the browser prompt to authenticate
# A session token is stored locally after authorization

Headless / CI Environments

For servers, containers, or CI pipelines where you can't open a browser, set the API key as an environment variable:

# Set your Anthropic API key
export ANTHROPIC_API_KEY=sk-ant-...

# Claude Code will use this key instead of OAuth
claude

Third-Party API Providers

Claude Code also supports connecting through Amazon Bedrock and Google Vertex AI. Configure these via environment variables:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

Setting Up CLAUDE.md

CLAUDE.md is the single most impactful configuration for Claude Code. It's a markdown file in your project root that gives Claude persistent context about your codebase. Build commands, code conventions, architecture decisions, testing instructions, anything Claude can't infer from the code alone.

# Inside Claude Code, run:
/init

# This analyzes your codebase and generates a starter CLAUDE.md
# with detected build systems, test frameworks, and code patterns

A good CLAUDE.md is concise. Aim for 50-100 lines in the root file. For each line, ask: "Would removing this cause Claude to make a mistake?" If not, cut it.

# CLAUDE.md

## Commands
- `npm run dev` - Start dev server on port 3000
- `npm run build` - Production build
- `npm test` - Run Jest tests
- `npm run lint` - ESLint check

## Architecture
- Next.js 15 with App Router
- PostgreSQL with Drizzle ORM
- Authentication via Clerk
- All API routes in src/app/api/

## Conventions
- Server components by default; use "use client" only when needed
- Database access only through Drizzle in server components/actions
- TypeScript strict mode; no any types
- Commit messages: imperative mood, < 72 chars

Extending Claude Code with MCP Servers

MCP (Model Context Protocol) servers give Claude Code access to external tools and data sources. You can connect it to GitHub, databases, Slack, file systems, search APIs, and custom services.

# Add an HTTP-based MCP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add a local stdio-based MCP server
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# List configured servers
claude mcp list

# Test a specific server
claude mcp get github

# Remove a server
claude mcp remove github

Useful MCP Servers

Slash Commands and Hooks

Built-in Slash Commands

Slash commands are shortcuts you type directly in the Claude Code REPL:

Custom Slash Commands

Create your own commands by adding markdown files to .claude/commands/ in your project:

# .claude/commands/review.md
Review the current git diff for:
- Security vulnerabilities
- Performance issues
- Missing error handling
- Style violations per our CLAUDE.md conventions

Focus on $ARGUMENTS or the entire diff if no specific area given.

Now /review auth module runs this prompt with "auth module" substituted for $ARGUMENTS.

Hooks

Hooks run your code at specific points in Claude Code's lifecycle. Configure them via /hooks or directly in .claude/settings.json.

// .claude/settings.json
{
  "hooks": {
    "postToolUse": [
      {
        "matcher": "edit_file|write_file",
        "type": "command",
        "command": "prettier --write $FILE_PATH"
      }
    ],
    "preToolUse": [
      {
        "matcher": "bash",
        "type": "command",
        "command": "echo 'Running: $TOOL_INPUT'"
      }
    ]
  }
}

Common hook patterns: auto-format files after edits, block dangerous commands, log tool usage, inject environment context at session start.

Claude Code vs Other CLI Coding Tools

Four tools dominate the terminal-based coding agent space in 2026. Each has a different strength.

Claude Code is the strongest choice for navigating large codebases and making complex, multi-file changes. If you mostly need quick single-file edits or want to use local models, Aider is a solid alternative. Gemini CLI is worth trying if you work with visual assets or want to experiment without paying upfront.

Troubleshooting

claude: command not found

Your shell hasn't picked up the new PATH entry. Close your terminal and open a new window. If that doesn't work, check that the install location is in your PATH:

# Check if claude is accessible
which claude

# If not found, the installer should have added it to your profile.
# Check ~/.bashrc, ~/.zshrc, or ~/.profile for the PATH addition.
# Then source it:
source ~/.zshrc   # or ~/.bashrc

EACCES Permission Errors (npm)

Never use sudo npm install -g. Either fix npm's default directory permissions or switch to nvm. See the npm installation section above for the fix.

Authentication Fails

If the browser redirect doesn't work, try these steps:

• Make sure you're logged into claude.ai in the browser that opens
• Check that your account is on a paid plan (Pro, Max, Teams, or Enterprise)
• Try claude logout then claude again to re-authenticate
• For CI environments, use ANTHROPIC_API_KEY instead of browser auth

Node.js Version Too Old (npm method)

The npm package requires Node.js 18+. Check your version with node --version. Use nvm to install a newer version if needed.

Run claude doctor

When something feels off, claude doctor auto-detects most configuration issues. It checks your Node.js version, authentication state, MCP server health, and file permissions. Run it before spending time debugging manually.

Frequently Asked Questions

How do I install Claude Code?

The recommended method is the native installer. On macOS or Linux: curl -fsSL https://claude.ai/install.sh | bash. On Windows: irm https://claude.ai/install.ps1 | iex in PowerShell. You can also use Homebrew (brew install --cask claude-code) or npm (npm install -g @anthropic-ai/claude-code).

Does Claude Code require Node.js?

No. The native installer and Homebrew methods have zero dependencies. Only the legacy npm method requires Node.js 18+.

What account do I need?

Any paid Anthropic account works: Claude Pro ($20/month), Claude Max ($100-200/month), Teams, Enterprise, or an Anthropic Console account with API credits. The free Claude.ai plan does not include Claude Code.

How do I authenticate in CI/CD pipelines?

Set the ANTHROPIC_API_KEY environment variable. Claude Code detects it automatically and skips the browser OAuth flow. You can also use Amazon Bedrock or Google Vertex AI credentials.

What is CLAUDE.md?

A markdown file in your project root that gives Claude persistent context: build commands, code conventions, architecture patterns. Run /init inside Claude Code to auto-generate one. It's the most important post-install configuration step.

Can I use Claude Code on Windows without WSL?

Yes. The native PowerShell installer (irm https://claude.ai/install.ps1 | iex) works directly on Windows. WSL is an alternative if you prefer a Linux environment.

How do I add MCP servers?

Use claude mcp add with the transport type and URL. For HTTP servers: claude mcp add --transport http name url. For local servers: claude mcp add name -- command args. Run claude mcp list to see configured servers.

How does Claude Code compare to Codex CLI?

Claude Code (powered by Claude Opus 4.6) leads in deep, multi-file reasoning across large codebases. Codex CLI (GPT-5) is strong at debugging and code analysis. Claude Code has better MCP support, auto-updates, and richer customization through slash commands and hooks. Codex CLI runs in a sandboxed environment by default.