Skip to main content
💡 install claude code💡 claude code install💡 claude code setup

Installation Guide

What you'll learn in this chapter: Prerequisites for Claude Code, OS-specific installation steps, and how to verify your installation

Prerequisites

Before starting this chapter, you'll need:

  • An internet connection
  • Basic familiarity with a terminal (Command Prompt / PowerShell / Terminal)

System Requirements​

RequirementMinimum
macOS13.0 (Ventura) or later
Windows10 (1809) or later + Git for Windows
LinuxUbuntu 20.04+ / Debian 10+ or other glibc-based distros
RAM4GB or more
ShellBash, Zsh, PowerShell, or CMD
Node.js Not Required

The native install (recommended) does not require Node.js. Node.js is only needed for the legacy npm install method.

Installing Claude Code​

Supports auto-updates and does not require Node.js.

macOS / Linux / WSL:

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

Windows PowerShell:

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

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Windows Prerequisite

Windows requires Git for Windows. Install it first if you don't have it.

Method 2: Package Manager​

Homebrew (macOS):

brew install --cask claude-code

WinGet (Windows):

winget install Anthropic.ClaudeCode
No Auto-Updates

Homebrew/WinGet installs do not auto-update. Run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode to update manually.

Legacy: npm Install (Not Recommended)

Requires Node.js 18+. Native install is recommended instead.

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

The -g flag installs globally, so you can use the claude command from any directory.

Verifying the Installation​

claude --version

Expected output (the version number may vary depending on when you install):

1.x.x (Claude Code)

For more detailed diagnostics:

claude doctor

First Run and Login​

cd your-project
claude

On first launch, a browser window opens with a login page:

  • Claude.ai account (Pro/Max/Team/Enterprise), or
  • Anthropic Console account (API billing)

Log in to complete authentication.

Subscription Plans

Claude Code is available on Pro, Max, Team, and Enterprise paid plans. The free plan is not supported. API key authentication is also available — see the next chapter for details.

Common Installation Issues​

Issue 1: claude: command not found​

Close and reopen your terminal completely to refresh the PATH environment variable. If that doesn't work, the install path is missing from your PATH.

Diagnosis:

# Check where claude is located in PowerShell
Get-Command claude -ErrorAction SilentlyContinue

# If nothing appears → PATH issue confirmed. Find where it was installed:
Get-ChildItem -Path $env:USERPROFILE -Recurse -Filter claude.exe -ErrorAction SilentlyContinue

Add to PATH (PowerShell):

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
Restart Terminal After PATH Change

After adding to PATH, you must close PowerShell completely and reopen it. Otherwise the same error will persist.

On macOS/Linux, if you encounter the same issue:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # macOS
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # Linux
source ~/.zshrc  # or source ~/.bashrc

If the problem persists, run claude doctor for detailed diagnostics.

Issue 2: EACCES: permission denied (macOS/Linux, npm install)​

mkdir ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

This issue does not occur with the native install method.

Issue 3: Installation fails on a corporate network​

You may need to configure a proxy:

# For npm install
npm config set proxy http://your-proxy-address:port
npm config set https-proxy http://your-proxy-address:port

Issue 4: Windows PowerShell execution policy error​

# Open PowerShell as Administrator and run
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Issue 5: claude opens the Claude Desktop app​

You installed the CLI, but when you type claude, it opens the Claude Desktop app. An older version of Claude Desktop registered Claude.exe in WindowsApps, so it has a higher PATH priority than the CLI.

Solution: update the Claude Desktop app to the latest version.

Issue 6: Browser does not open during login from WSL·SSH​

On WSL2, remote SSH, or containers, the browser opens on a different host during claude's first launch, so the redirect cannot return to Claude Code. After login, a login code appears — paste it into the terminal's Paste code here if prompted prompt.

If the browser still does not open on WSL2, point it to the Windows browser path:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

Or, at the interactive login prompt, press the c key to copy the OAuth URL to the clipboard and paste it directly into your browser.

Issue 7: Corporate TLS interception​

SSL certificate verification failed or unable to get local issuer certificate. A corporate proxy intercepts TLS with its own certificate.

Load the company CA bundle and set the environment variable permanently:

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
Do Not Disable Verification

NODE_TLS_REJECT_UNAUTHORIZED=0 turns off certificate verification entirely — a major security risk. Use the company CA bundle instead.

Issue 8: Illegal instruction on older CPUs​

claude --version raises Illegal instruction. This occurs on pre-2013 CPUs (no AVX support) or in VMs where the hypervisor does not expose AVX to the guest.

Diagnosis (Linux VPS/VM):

grep -m1 -o avx /proc/cpuinfo

If the output is empty, AVX is not available. There is currently no fix — see GitHub issue #50384. Alternative installers like Homebrew or WinGet use the same binary, so they do not help either.

Issue 9: WSL1 Exec format error​

cannot execute binary file: Exec format error when running claude on WSL. This is a WSL1-only regression (issue #38788).

The cleanest fix — switch from PowerShell to WSL2:

wsl --set-version <DistroName> 2

Key Takeaways​

  • Native install is recommended — no Node.js required, auto-updates included
  • macOS/Linux: curl ... | bash / Windows: irm ... | iex
  • Verify with claude --version
  • First run authenticates via browser login
  • Paid plan (Pro/Max/Team/Enterprise) required
Get weekly Claude Code tips by email

Get weekly Claude Code tips by email — real usage insights, delivered free. Subscribe →

이 챕터를 완료하셨나요?

학습 진도를 체크하여 나의 로드맵 달성률을 높여보세요.