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
- 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.
- Native installs update themselves in the background; Homebrew, WinGet and apt installs need manual upgrades.
- After installing, open a new window and run claude --version; command not found almost always means the install folder isn't on your PATH.
- 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 computer | Recommended install | Where to run it |
|---|---|---|
| Mac (Apple silicon or Intel, same command) | Native installer (curl) | Terminal app |
| Mac that already uses Homebrew | Native installer, or Homebrew (manual upgrades) | Terminal app |
| Windows 10 1809 or later, Windows 11 | Native installer (irm) | PowerShell |
| Windows where you can only open CMD | CMD native installer | Command Prompt (CMD) |
| Windows, and you like WinGet | WinGet (manual upgrades) | PowerShell |
| Windows, projects and tools live in WSL | Linux native installer inside WSL | WSL Linux terminal |
| Ubuntu, Debian, Fedora, RHEL, Alpine | Native installer, or apt, dnf, apk | Linux terminal |
| Work computer without admin rights | Native installer (installs into your user folder) | As above, by OS |
| Installed with npm before | Switch to the native installer, then remove the npm copy | As 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>, withPSat the front. PressWin + Xand choose Windows PowerShell or Terminal to open it. - CMD (Command Prompt) shows
C:\Users\YourName>, withoutPS.
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.
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?
| Item | Official requirement |
|---|---|
| Operating system | macOS 13.0+; Windows 10 1809+ or Windows Server 2019+; Ubuntu 20.04+; Debian 10+; Alpine Linux 3.19+ |
| Memory | 4 GB+ RAM |
| Processor | x64 or ARM64 (32-bit Windows is not supported) |
| Network | Internet connection required |
| Shell | Bash, Zsh, PowerShell or CMD |
| Location | An Anthropic-supported country or region |
| Node.js | Not needed for the native installer; npm installs need Node.js 22+ |
| Git | Optional; Git for Windows recommended on native Windows, not needed in WSL |
| Disk space | Not 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-codeHomebrew 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 gnupgDownload 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.ascCheck that the key is Anthropic’s:
gpg --show-keys /etc/apt/keyrings/claude-code.ascThe 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-codeFedora 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 | iexirm 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.ClaudeCodeWinGet 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 usesudo 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 --versionstarts with 12, npm skips Claude Code’s postinstall step by default andclaudereportsclaude native binary not installed. The docs suggest switching to the native installer, or, to stay on npm, allowing the scripts with theallow-scriptssetting as described in their npm 12 fix 3. - Upgrade with
npm install -g @anthropic-ai/claude-code@latest. The docs warn againstnpm update -g, which may not move you to the newest release 1.
How do I check the install worked?
- Close the window you installed from and open a new terminal. The old window keeps its pre-install PATH and may not find
claude3. - Run this. A version number such as
2.1.211 (Claude Code)means it’s installed 1:
# Any terminal
claude --version
- 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
cat 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 hereprompt 5. - You want to sign in before the first session. Run
claude auth loginin 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.
How do I update and switch release channels?
| Install method | Updates itself? | Manual update command |
|---|---|---|
| Native installer | Yes, downloads in the background, applies on next launch | claude update |
| Homebrew | No | brew upgrade claude-code or brew upgrade claude-code@latest |
| WinGet | No | winget upgrade Anthropic.ClaudeCode |
| apt | No | sudo apt update && sudo apt upgrade claude-code |
| dnf | No | sudo dnf upgrade claude-code |
| apk | No | apk update && apk upgrade claude-code |
| npm | Yes (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.jsonfile (%USERPROFILE%\.claudeand%USERPROFILE%\.claude.jsonon Windows). - Project level.
.claude/and.mcp.jsoninside 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.
- 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.
- 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 theirmline, or stay in CMD and run theinstall.cmdline.The token '&&' is not a valid statement separator. You’re in PowerShell but pasted the CMD command. Run theirmline.A parameter cannot be found that matches parameter name 'fsSL'or'bash' is not recognized. You pasted the macOS/Linuxcurl … | bashline on Windows. Run theirmline.
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 CurrentUserin PowerShell, then retry. - Call
npm.cmdandclaude.cmd. The policy covers.ps1files, not.cmd. - Use the PowerShell native installer. It installs a binary, not a
.ps1script.
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_PATHinsettings.jsonas shown in the Windows section. The file name must bebash.exe,sh.exe,bashorsh; pointing it atgit-bash.exeis 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> 23.- The npm install prints
exec: node: not found. WSL is picking up the Windows Node.js. Runwhich 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
cto 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:
- Type
/logoutin Claude Code. - Close Claude Code.
- Run
claudeagain 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
Kelvin Wang
Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.
More about me