This document covers installing Claude Code and completing initial setup to start using the tool. It focuses on the installation methods, authentication configuration, and verification steps needed before beginning development work.
For configuration management details, see Configuration Management. For CLI command reference, see CLI Commands & Interaction Modes. For DevContainer-based development environment setup, see DevContainer Configuration.
Claude Code provides multiple installation methods optimized for different platforms and package managers. The npm-based installation is deprecated as of version 2.1.15 and users should migrate to platform-native installers.
MacOS/Linux (Shell Script Installer)
This is the primary installation method for Unix-based systems. The script detects the platform and installs the appropriate binary.
Homebrew (MacOS/Linux)
Alternative package manager installation for systems with Homebrew.
Windows (PowerShell Installer)
Recommended installation method for Windows systems using PowerShell.
WinGet (Windows)
Windows Package Manager alternative for Windows 10+ systems.
npm (Deprecated)
Legacy installation method. As of 2.1.15, users receive deprecation warnings directing them to run claude install or visit the setup documentation.
Sources: README.md19-44 CHANGELOG.md390-391
After installation, Claude Code requires authentication to access the Anthropic API. The tool supports multiple authentication methods depending on the deployment environment.
Sources: CHANGELOG.md155-156 CHANGELOG.md459
The primary authentication method uses OAuth with the Anthropic platform:
claude auth loginplatform.claude.com OAuth consent screen~/.claude/ directoryIf the browser fails to open automatically, press c to copy the OAuth URL to clipboard (added in 2.1.10).
For programmatic access or CI/CD environments:
The ANTHROPIC_API_KEY environment variable is read on startup.
AWS Bedrock:
~/.aws/credentialsGoogle Vertex:
Palantir Foundry:
Sources: CHANGELOG.md133 CHANGELOG.md285
On first run, Claude Code creates the configuration directory structure and initializes default settings.
~/.claude/
├── settings.json # User-level settings
├── managed-settings.json # Enterprise-managed settings (if present)
├── sessions/ # Conversation history
├── skills/ # User-defined skills
├── agents/ # Custom agent definitions
└── backups/ # Configuration backups (added 2.1.47)
Project-level configuration can also exist:
<project-root>/.claude/
├── settings.json # Project-level settings
├── settings.local.json # Local overrides (gitignored)
├── skills/ # Project-specific skills
├── agents/ # Project-specific agents
└── CLAUDE.md # Project context file
Sources: CHANGELOG.md92
Configuration follows a hierarchical merge pattern:
Enterprise settings (if present) have highest priority and cannot be overridden by user or project settings. This enables organizational policy enforcement.
Sources: CHANGELOG.md28
After installation, verify the setup by running basic commands.
Confirms the binary is accessible and displays the installed version.
The claude doctor command performs diagnostic checks:
This command verifies:
Diagnostic Output Sections:
| Section | Purpose |
|---|---|
| Installation | Shows installation method and binary location |
| Authentication | Displays logged-in user and provider |
| Updates | Shows current version, channel, and available updates |
| API Access | Tests connectivity to Anthropic API endpoints |
| Model Availability | Lists accessible models for current account |
Sources: CHANGELOG.md65 CHANGELOG.md465-466
Displays current authentication state including:
Navigate to a project directory and run:
On first run in a project:
.claude/ directory if it doesn't exist/helpSources: CHANGELOG.md424 CHANGELOG.md40
Problem: claude doctor misclassifies mise or asdf-managed installations as native installs.
Fixed in: 2.1.47
Verification: Run claude doctor and check the "Installation" section identifies the correct package manager.
Sources: CHANGELOG.md65
Problem: Orphaned Claude Code processes after terminal disconnect on macOS.
Fixed in: 2.1.46
Problem: Process hangs after session close.
Fixed in: 2.1.39
Sources: CHANGELOG.md105 CHANGELOG.md174
Problem: AWS auth refresh hanging indefinitely.
Fixed in: 2.1.43 with 3-minute timeout
Problem: VS Code OAuth token expiration causing 401 errors.
Fixed in: 2.1.27
Sources: CHANGELOG.md133 CHANGELOG.md285
As of 2.1.41, Claude Code includes a guard against launching inside another Claude Code session to prevent nested shell issues.
Sources: CHANGELOG.md147
For containerized development environments, Claude Code can be installed via the provided DevContainer configuration.
The .devcontainer/Dockerfile provides a reproducible installation environment:
Key Components:
| Component | Purpose |
|---|---|
| Base Image | node:20 - Node.js runtime |
| Package Manager | npm global installation |
| User | Non-root node user |
| Network Security | init-firewall.sh script for network isolation |
| Persistent Storage | Mounts for workspace, config, history, packages |
The DevContainer includes network firewall initialization:
This script configures iptables rules to:
Sudoers Configuration:
node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh
The node user has limited sudo access only for firewall initialization.
Sources: .devcontainer/Dockerfile1-92
Sources: .devcontainer/Dockerfile82-92
Users with npm-based installations should migrate to native installers:
Check Current Installation:
Uninstall npm Package:
Install via Native Method:
Verify Installation:
Authentication Carries Over:
The ~/.claude/ directory and authentication tokens are preserved across installation methods.
Configuration backups are automatically created in ~/.claude/backups/ (added in 2.1.47) with timestamps and rotation (keeping 5 most recent).
Sources: CHANGELOG.md92 CHANGELOG.md351
After successful installation and verification:
claude to beginSources: README.md1-73
Refresh this wiki