Appearance

Language

Mastering AI agents

How to Install Claude Code in 2026: macOS, Windows and Linux Commands, Plus Common Errors

A complete install guide for the Claude Code terminal CLI: work out whether you're on a Mac, Windows (PowerShell, CMD or WSL) or Linux, run the matching official command, sign in, update and uninstall, then fix the usual errors: command not found, PATH, PowerShell execution policy and corporate proxies.

Kelvin Wang · · 18 min read

Key points

  1. The official recommendation is the native installer: curl on macOS, Linux and WSL, irm in Windows PowerShell. No Node.js and no administrator rights needed.
  2. Native installs update themselves in the background; Homebrew, WinGet and apt installs need manual upgrades.
  3. After installing, open a new window and run claude --version; command not found almost always means the install folder isn't on your PATH.
  4. Keep one copy of Claude Code per machine: an npm install next to a native install causes version mix-ups.

A terminal is a text-only window: you type a command, press Enter, and the computer prints the result. The Claude Code CLI is the AI coding tool that runs inside that window. Installing it takes one line; beginners usually get stuck earlier, not knowing which kind of terminal they have open or which line to paste. Every command and claim below follows Anthropic’s official documentation as checked on November 15, 2026 1. Claude Code needs a paid Claude plan (Pro, Max, Ultra, Team or Enterprise) or a Claude Console account; the free plan can’t use it 1.

If you’d rather skip the terminal, Claude Code also ships as a desktop app you install from a download.

Go deeper Claude Code Desktop vs CLI vs VS Code (2026): Which One Should a Beginner Start With? Same engine in all three; they differ in how you work and which commands you get.

Which situation is your computer in?

Find your row, then go to the section for the install method it names.

Your computerRecommended installWhere to run it
Mac (Apple silicon or Intel, same command)Native installer (curl)Terminal app
Mac that already uses HomebrewNative installer, or Homebrew (manual upgrades)Terminal app
Windows 10 1809 or later, Windows 11Native installer (irm)PowerShell
Windows where you can only open CMDCMD native installerCommand Prompt (CMD)
Windows, and you like WinGetWinGet (manual upgrades)PowerShell
Windows, projects and tools live in WSLLinux native installer inside WSLWSL Linux terminal
Ubuntu, Debian, Fedora, RHEL, AlpineNative installer, or apt, dnf, apkLinux terminal
Work computer without admin rightsNative installer (installs into your user folder)As above, by OS
Installed with npm beforeSwitch to the native installer, then remove the npm copyAs above, by OS

Is my Mac Apple silicon or Intel?

Open the Apple menu → About This Mac. An item labelled Chip means Apple silicon; Processor means Intel 7. Claude Code supports both with the same command, and the installer picks the right build 1. What matters is the macOS version: Claude Code needs macOS 13.0 or later.

Homebrew is a package manager for the Mac: one command installs, upgrades or removes software. To see whether you have it, run brew --version in Terminal; a version number means yes. You don’t need it for Claude Code. Homebrew currently supports macOS 15 or later on Apple silicon, and Intel Macs are its lowest support tier 8, so on an older Mac the native installer is the simpler path.

Am I in PowerShell or CMD on Windows?

Windows has two command lines, and their commands don’t mix. Look at the start of each line:

  • PowerShell shows PS C:\Users\YourName>, with PS at the front. Press Win + X and choose Windows PowerShell or Terminal to open it.
  • CMD (Command Prompt) shows C:\Users\YourName>, without PS.

The Start menu also has a “Windows PowerShell (x86)” entry. That one is 32-bit and triggers a “does not support 32-bit Windows” error; open the entry without x86 3.

Git for Windows is Git for Windows, bundled with Git Bash. The docs recommend it on native Windows so Claude Code can run commands through its Bash tool; without it Claude Code uses PowerShell instead 1. Check with git --version in PowerShell. The setup guide walks through installing it.

Go deeper Set Up Your Computer for AI Coding from Zero: Terminal, Git, GitHub, Node.js Opening a terminal, installing Git for Windows, and checking each step.

Should I use WSL?

WSL (Windows Subsystem for Linux) is the Linux environment built into Windows. The docs frame the choice like this 1:

  • Your projects and tools are Windows ones. Install on native Windows (PowerShell or CMD); no WSL needed.
  • You need Linux toolchains, or sandboxing to restrict the commands Claude runs. Use WSL 2. Native Windows and WSL 1 don’t support sandboxing.
  • Only WSL 1 is available. It installs, but there’s a known issue; see the errors section.

If WSL is already installed, run wsl -l -v in PowerShell: the VERSION column shows 1 or 2 for each distribution 10. Installing WSL itself with wsl --install needs PowerShell opened with “Run as administrator”, then a restart 10. On a work machine without admin rights, use native Windows.

What if my work computer has no admin rights?

The native installer writes into your own user folder: ~/.local/bin and ~/.local/share/claude on macOS and Linux, %USERPROFILE%\.local\bin on Windows. The docs say explicitly that the Windows install doesn’t need to run as Administrator 1 3. The routes that do need admin are installing WSL and installing from Linux repositories with sudo apt or sudo dnf.

The two usual obstacles on company networks are proxies and firewalls that inspect encrypted traffic; fixes are in the errors section. If endpoint security blocks the commands claude.exe starts, the docs suggest asking IT to allowlist claude.exe and the cmd.exe and bash.exe processes it spawns 3.

What are the system requirements?

ItemOfficial requirement
Operating systemmacOS 13.0+; Windows 10 1809+ or Windows Server 2019+; Ubuntu 20.04+; Debian 10+; Alpine Linux 3.19+
Memory4 GB+ RAM
Processorx64 or ARM64 (32-bit Windows is not supported)
NetworkInternet connection required
ShellBash, Zsh, PowerShell or CMD
LocationAn Anthropic-supported country or region
Node.jsNot needed for the native installer; npm installs need Node.js 22+
GitOptional; Git for Windows recommended on native Windows, not needed in WSL
Disk spaceNot stated in the official docs

Source: Claude Code Advanced setup page, checked 2026-11-15.

How do I install on macOS, Linux and WSL?

Open a terminal (on a Mac press Cmd + Space and search for Terminal; on most Linux distributions press Ctrl + Alt + T; for WSL open a distribution such as Ubuntu from the Start menu), paste this line and press Enter:

# Run in macOS Terminal, a Linux terminal, or inside WSL
curl -fsSL https://claude.ai/install.sh | bash

It downloads and runs the installer from claude.ai. There’s no progress display while it downloads, so leave the window open; “Claude Code successfully installed!” means it’s done 4. With WSL, install and launch inside the WSL terminal, not from PowerShell 1.

Alpine and other musl-based systems ship without bash and curl, so the command fails with not found until you add them 1:

# Alpine Linux
apk add bash curl

Homebrew (macOS)

# Run in macOS Terminal
brew install --cask claude-code

Homebrew offers two casks. claude-code follows the stable channel, usually about a week behind and skipping releases with major regressions; claude-code@latest gets each release as soon as it ships. Homebrew installs don’t update themselves 1.

apt (Ubuntu, Debian)

Anthropic publishes a signed apt repository. Make sure curl and gpg exist first:

# Run in an Ubuntu or Debian terminal
sudo apt install curl gnupg

Download the signing key:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc

Check that the key is Anthropic’s:

gpg --show-keys /etc/apt/keyrings/claude-code.asc

The only fingerprint printed should be 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. Then register the stable repository and install:

echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Fedora and RHEL use dnf, Alpine uses apk; the commands are on the Advanced setup page 1. Package-manager installs aren’t updated by Claude Code itself; they follow your normal system upgrades.

How do I install on Windows?

PowerShell

# Run in PowerShell (prompt starts with PS)
irm https://claude.ai/install.ps1 | iex

irm downloads, iex runs, so paste both halves. Running only the irm part prints the script text and installs nothing 3.

CMD

:: Run in Command Prompt (no PS at the start)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

WinGet

# Run in PowerShell
winget install Anthropic.ClaudeCode

WinGet is the Windows package manager, included through App Installer on Windows 11 and modern Windows 10 9. WinGet installs don’t update themselves 1.

PowerShell versus CMD only changes which line you run; the result is the same 1. Afterwards, start claude from any terminal.

If Git for Windows is installed but Claude Code can’t find Git Bash, set the path to bash.exe in your settings.json 1:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

The user-level settings file is %USERPROFILE%\.claude\settings.json. If Git lives somewhere else, run where.exe git in PowerShell to find it and use the bin\bash.exe inside that installation 3.

Can I still install with npm?

Yes, but the docs list it under advanced installation options and recommend the native installer up front 1. npm is the package manager that comes with Node.js; the npm package needs Node.js 22 or later, and it installs the same native binary, which doesn’t use your Node.js at runtime 1.

# macOS, Linux or WSL terminal, or Windows PowerShell
npm install -g @anthropic-ai/claude-code@latest
  • Don’t add sudo. The docs say not to use sudo npm install -g: it causes permission problems and security risks, and since Claude Code updates itself without sudo, an install that needed sudo can’t update 1.
  • npm 12 needs an extra step. If npm --version starts with 12, npm skips Claude Code’s postinstall step by default and claude reports claude native binary not installed. The docs suggest switching to the native installer, or, to stay on npm, allowing the scripts with the allow-scripts setting as described in their npm 12 fix 3.
  • Upgrade with npm install -g @anthropic-ai/claude-code@latest. The docs warn against npm update -g, which may not move you to the newest release 1.

How do I check the install worked?

  1. Close the window you installed from and open a new terminal. The old window keeps its pre-install PATH and may not find claude 3.
  2. Run this. A version number such as 2.1.211 (Claude Code) means it’s installed 1:
# Any terminal
claude --version
  1. For a fuller check, run claude doctor. It doesn’t start a session; it prints install health, settings-file errors, the last auto-update result, and suggested fixes for anything wrong 1.
claude doctor

How do I sign in the first time?

cd into your project folder, then start Claude Code:

# macOS, Linux or WSL terminal, or Windows PowerShell
cd /path/to/your/project
claude

Replace /path/to/your/project with your project’s path. The first launch opens a browser to sign in; when it’s done the terminal shows Login successful and asks you to press Enter 5. Your credentials are saved, so you won’t sign in every time 2.

  • The browser didn’t open. Press c at the login screen to copy the URL and paste it into a browser yourself 5.
  • The browser shows a code after you sign in. Paste it into the terminal at the Paste code here prompt 5.
  • You want to sign in before the first session. Run claude auth login in your terminal 5.

Two kinds of account can sign in 5:

  • A Claude subscription (Pro, Max, Ultra, Team, Enterprise). Sign in with your claude.ai account; usage is covered by the monthly fee, up to the plan’s limits. The docs mark this as the recommended option 2.
  • Claude Console (API). Pay per use from prepaid credits. On first sign-in, Console creates a “Claude Code” workspace so you can track the spend in one place 2.

If the ANTHROPIC_API_KEY environment variable is set, Claude Code asks whether to use it; say yes and it skips the login and bills the API instead 5. To stay on your subscription, don’t set that variable.

Inside a session, type /help for commands, /login to switch accounts, /logout to sign out, press Esc to interrupt Claude, and press Ctrl + D twice on an empty prompt to leave 2 4. What to do after the first conversation (CLAUDE.md, plan mode, skills) is in the full tutorial.

Go deeper Claude Code Tutorial 2026: Install, CLAUDE.md, Skills, and Your First Website The next steps after installing: CLAUDE.md, plan mode, skills, hooks, MCP.

How do I update and switch release channels?

Install methodUpdates itself?Manual update command
Native installerYes, downloads in the background, applies on next launchclaude update
HomebrewNobrew upgrade claude-code or brew upgrade claude-code@latest
WinGetNowinget upgrade Anthropic.ClaudeCode
aptNosudo apt update && sudo apt upgrade claude-code
dnfNosudo dnf upgrade claude-code
apkNoapk update && apk upgrade claude-code
npmYes (if the npm global folder is writable)npm install -g @anthropic-ai/claude-code@latest

Source: Claude Code Advanced setup page, checked 2026-11-15.

On Homebrew and WinGet you can let Claude Code run the upgrade for you by setting the environment variable CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1. On WinGet the upgrade may fail while Claude Code is running, because Windows locks the running file; it then shows the manual command instead 1. Homebrew keeps old versions after upgrades, so run brew cleanup now and then.

What is a release channel?

Native installs follow one of two channels 1:

  • latest (default). New features as soon as they ship.
  • stable. A version that’s usually about a week old, skipping releases with major regressions.

Switch in Claude Code with /config → Auto-update channel, or add this to ~/.claude/settings.json:

{
  "autoUpdatesChannel": "stable"
}

Moving from latest to stable downgrades a native install to the stable version. To avoid that, choose “Stay on current version” when you switch to stable in /config; it sets your current version as the minimumVersion 1. A newly launched model can need a newer version than stable serves; switch back to latest to use it right away. Homebrew picks the channel by cask name, and apt, dnf and apk by repository; they ignore this setting.

You can also pick a channel or version at install time:

# macOS, Linux, WSL: install the stable channel
curl -fsSL https://claude.ai/install.sh | bash -s stable
# Windows PowerShell: install the stable channel
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
:: Windows CMD: install the stable channel
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd stable && del install.cmd

Replace stable with a version number such as 2.1.89 to install that version 1.

To turn off background updates, add "DISABLE_AUTOUPDATER": "1" under env in settings.json. That only stops the background check; claude update still works 1.

How do I uninstall Claude Code?

Remove it the way you installed it. If claude still runs afterwards, there’s a second copy; see “Two installs at once” in the errors section 1.

Native

# macOS, Linux, WSL
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
# Windows PowerShell
Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew

# macOS Terminal; use the second line if you installed the latest cask
brew uninstall --cask claude-code
brew uninstall --cask claude-code@latest

WinGet

# Windows PowerShell
winget uninstall Anthropic.ClaudeCode

apt / dnf

# Ubuntu, Debian
sudo apt remove claude-code
sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc
# Fedora, RHEL
sudo dnf remove claude-code
sudo rm /etc/yum.repos.d/claude-code.repo

npm

# Any terminal
npm uninstall -g @anthropic-ai/claude-code

Should I delete the config files too?

The commands above only remove the program. Settings, allowed tools, MCP configuration and session history live elsewhere 1:

  • User level. The ~/.claude/ folder and the ~/.claude.json file (%USERPROFILE%\.claude and %USERPROFILE%\.claude.json on Windows).
  • Project level. .claude/ and .mcp.json inside each project folder.

Deleting them removes every setting and all session history for good. The VS Code extension, the JetBrains plugin and the desktop app also write to ~/.claude/; if any of them is still installed it recreates the folder, so uninstall them first for a clean removal 1.

# macOS, Linux, WSL: remove user settings
rm -rf ~/.claude
rm ~/.claude.json
# Windows PowerShell: remove user settings
Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

How do I fix common install errors?

The official troubleshooting page has a full error-to-fix table 3; these are the ones beginners hit most.

command not found: claude, or ‘claude’ is not recognized

PATH is the list of folders your terminal searches for programs: type claude and it only looks in those folders. The installer puts claude in ~/.local/bin (%USERPROFILE%\.local\bin on Windows); if that folder isn’t on PATH, you get this error. The installer prints the fix under Setup notes at the end, but doesn’t change PATH itself 3.

  1. Open a new window and try again. Old windows, and terminals inside an editor, keep the old PATH; with an editor such as VS Code, quit and reopen the whole editor 3.
  2. Still failing? Add the folder to PATH for your shell:
# macOS (default zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Linux (bash, the default on most distributions)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Windows PowerShell; reopen PowerShell afterwards
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

If you use bash on macOS, the line goes in ~/.bash_profile, not ~/.bashrc 3. If the echo line prints permission denied, your shell config file isn’t writable; the docs explain how to fix its owner or permissions 3. If claude disappeared on Windows right after an auto-update, the file swap failed, and the docs give a command to restore it from the claude.exe.old.* backup 3.

Pasted the wrong command on Windows

The error message tells you which terminal you’re really in 3:

  • 'irm' is not recognized. You’re in CMD. Open PowerShell and run the irm line, or stay in CMD and run the install.cmd line.
  • The token '&&' is not a valid statement separator. You’re in PowerShell but pasted the CMD command. Run the irm line.
  • A parameter cannot be found that matches parameter name 'fsSL' or 'bash' is not recognized. You pasted the macOS/Linux curl … | bash line on Windows. Run the irm line.

running scripts is disabled on this system

PowerShell’s execution policy is blocking the .ps1 launcher scripts npm creates. It only happens with npm installs; the native irm … | iex install isn’t affected 3. Pick one fix:

  • Allow local scripts for your user. Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser in PowerShell, then retry.
  • Call npm.cmd and claude.cmd. The policy covers .ps1 files, not .cmd.
  • Use the PowerShell native installer. It installs a binary, not a .ps1 script.

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Neither Git Bash nor PowerShell was found; Claude Code needs at least one 3:

  • PowerShell is missing from PATH. Its default location is C:\Windows\System32\WindowsPowerShell\v1.0\. Add it back, or install PowerShell 7.
  • You want Git Bash. Install Git for Windows, choose “Add to PATH” during setup, then restart your terminal.
  • Git is installed but not found. Set CLAUDE_CODE_GIT_BASH_PATH in settings.json as shown in the Windows section. The file name must be bash.exe, sh.exe, bash or sh; pointing it at git-bash.exe is ignored.

npm permission errors (EACCES)

If an npm install fails with EACCES: permission denied, the docs say don’t rerun it with sudo: switch to the native installer and remove the npm copy 1 3. If the native installer itself hits a permission error, the message names the folder it couldn’t write; on macOS and Linux you can make yourself the owner of ~/.local again 3:

# macOS or Linux terminal; asks for your login password
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

Corporate networks: proxies and certificate errors

First test whether you can reach the download server. A first line with 200 means you can 3:

# macOS, Linux, WSL
curl -sI https://downloads.claude.ai/claude-code-releases/latest
# Windows PowerShell (type curl.exe; curl in PowerShell is a different command)
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

If your company routes traffic through a proxy (a server every outbound connection passes through), set its address before installing. Ask IT for the URL or check your browser’s proxy settings 3:

# macOS, Linux, WSL; replace the URL with your company's proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell; replace the URL with your company's proxy
$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

Certificate errors such as unable to get local issuer certificate or SELF_SIGNED_CERT_IN_CHAIN usually mean the proxy inspects encrypted traffic. On macOS and Linux, get your company’s root CA as a PEM file from IT and point both CURL_CA_BUNDLE and NODE_EXTRA_CA_CERTS at it before installing; the Windows PowerShell installer uses the Windows certificate store, so ask IT to add the certificate there 3. On older Windows 10, Could not create SSL/TLS secure channel means you should enable TLS 1.2 in the same PowerShell window first 4:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

Full proxy and certificate setup, including Claude Code’s own connections after install, is on the official network configuration page 6.

The install command prints HTML, or returns 403

syntax error near unexpected token '<', CMD’s < was unexpected at this time, and PowerShell’s System.Xml.XmlDocument all mean you downloaded a web page instead of the install script. If the output mentions “App unavailable in region”, Claude Code isn’t available where you are. Otherwise it’s usually a temporary network problem: wait a few minutes and retry, or install with Homebrew (Mac) or WinGet (Windows) instead 3. A bare 403 can also come from a corporate proxy or firewall, so run the connectivity test above first.

Problems inside WSL

  • cannot execute binary file: Exec format error. You’re on WSL 1 and hitting a known regression. The cleanest fix is converting the distribution to WSL 2 from PowerShell: wsl --set-version <DistroName> 2 3.
  • The npm install prints exec: node: not found. WSL is picking up the Windows Node.js. Run which node; a path starting with /mnt/c/ is the Windows one. Install Node.js inside WSL with your distribution’s package manager or nvm 3. The native installer avoids this entirely.
  • No browser opens at login, or it shows a localhost connection error. Press c to copy the login URL, open it in your Windows browser, sign in, and paste the code it shows back into the terminal 3.

Two installs at once (npm and native)

More than one copy leads to mismatched versions and updates that don’t seem to take. The docs say keep one, the native install 3. First see how many claude binaries you have:

# macOS, Linux, WSL: list every claude on your PATH
which -a claude
ls -la ~/.local/bin/claude
npm -g ls @anthropic-ai/claude-code 2>/dev/null
# Windows PowerShell
where.exe claude

Then remove the extras: npm uninstall -g @anthropic-ai/claude-code for the npm copy; rm -rf ~/.claude/local for the legacy local npm install that older Claude Code versions created; Homebrew and WinGet copies as in the uninstall section 3. If typing claude on Windows opens the desktop app, an older Claude Desktop registered that name first; update the desktop app to the latest version 3.

Sign-in fails

When the cause isn’t clear, the docs’ reset is 3:

  1. Type /logout in Claude Code.
  2. Close Claude Code.
  3. Run claude again and sign in.

If you’re asked to sign in again often, check that your computer’s clock is correct; token validation depends on accurate time 3.

Sources

  1. 1. Advanced setup · Claude Code Docs · checked 2026-11-15
  2. 2. Quickstart · Claude Code Docs · checked 2026-11-15
  3. 3. Troubleshoot installation and login · Claude Code Docs · checked 2026-11-15
  4. 4. Terminal guide for new users · Claude Code Docs · checked 2026-11-15
  5. 5. Authentication · Claude Code Docs · checked 2026-11-15
  6. 6. Enterprise network configuration · Claude Code Docs · checked 2026-11-15
  7. 7. Mac computers with Apple silicon · Apple Support · checked 2026-11-15
  8. 8. Installation · Homebrew Documentation · checked 2026-11-15
  9. 9. Use WinGet to install and manage applications · Microsoft Learn · checked 2026-11-15
  10. 10. Install WSL · Microsoft Learn · checked 2026-11-15

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me