Claude Code is Anthropic’s terminal-based coding agent. You run it inside a project folder, describe what you want in plain English, and it reads your files, makes changes, runs tests, and handles Git.
Installing it takes about a minute. This guide covers every install method, how to verify it worked, how to log in, and the errors people actually hit.
Before You Start: What You Need
A paid Claude account. This trips up a lot of people, so it’s worth saying up front: the free Claude.ai plan does not include Claude Code. You need one of the following:
- A Claude Pro, Max, Team, or Enterprise subscription
- A Claude Console account with pre-paid API credits
- Access through Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry
A supported system:
| Requirement | Details |
|---|---|
| macOS | 13.0 or later |
| Windows | 10 (build 1809+) or Server 2019+ |
| Linux | Ubuntu 20.04+, Debian 10+, or Alpine 3.19+ |
| Hardware | 4 GB+ RAM, x64 or ARM64 |
| Shell | Bash, Zsh, PowerShell, or CMD |
| Network | Internet connection required |
You also need to be in a country Anthropic supports.
Never used a terminal? That’s fine, but be honest with yourself about it — Claude Code lives entirely in the terminal. There’s also a desktop app if you’d rather have a graphical interface, and it’s a reasonable place to start.
Method 1: Native Installer (Recommended)
This is the method Anthropic recommends. It downloads a standalone binary — no Node.js, no package manager, and it keeps itself updated in the background.
macOS, Linux, or 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
A quick note on the two Windows commands, because mixing them up is the single most common Windows error: your prompt shows PS C:\ in PowerShell and C:\ without the PS in CMD. If you get The token '&&' is not a valid statement separator, you ran the CMD command in PowerShell. If you get 'irm' is not recognized, you ran the PowerShell command in CMD.
Method 2: Homebrew (macOS and Linux)
brew install --cask claude-code
There are two casks. claude-code follows the stable channel, which runs about a week behind and skips releases with known major regressions. claude-code@latest gets every release as it ships.
Homebrew installs do not auto-update. You’ll need to run this yourself:
brew upgrade claude-code
Method 3: WinGet (Windows)
winget install Anthropic.ClaudeCode
Also doesn’t auto-update. Upgrade with:
winget upgrade Anthropic.ClaudeCode
Method 4: npm
npm install -g @anthropic-ai/claude-code
This installs the same native binary as the standalone installer — npm is just the delivery mechanism. As of v2.1.198 the package wants Node.js 22 or later, though on an older version npm prints an EBADENGINE warning and installs anyway, and the binary still runs because it doesn’t use your Node at runtime.
Do not run this with sudo. sudo npm install -g causes permission problems and is a genuine security risk. If you’re hitting permission errors, fix your npm prefix instead of escalating.
To upgrade, use npm install -g @anthropic-ai/claude-code@latest rather than npm update -g — the latter respects the original semver range and may not move you to the newest release.
Method 5: Linux Package Managers
Anthropic publishes signed apt, dnf, and apk repositories. These are the right choice if you manage servers and want Claude Code to update through your normal system upgrade workflow.
Debian / Ubuntu (apt):
sudo apt install curl gnupg
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
Verify the key belongs to Anthropic before trusting it:
gpg --show-keys /etc/apt/keyrings/claude-code.asc
The fingerprint should read 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. If it doesn’t, stop and re-download.
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 / RHEL (dnf) and Alpine (apk) follow the same pattern with their own repository configuration — see the official setup docs for the exact commands.
Verify the Install
claude --version
You should see something like 2.1.211 (Claude Code). If you get command not found, jump to the troubleshooting section below.
For a deeper check that validates your settings files and flags configuration problems without starting a session:
claude doctor
Log In
Navigate to a project folder and start Claude Code:
cd /path/to/your/project
claude
On first run it opens your browser to authenticate. Follow the prompts, and your credentials are stored — you won’t need to log in again.
If you have ANTHROPIC_API_KEY set as an environment variable, Claude Code skips the browser and asks you to approve the key instead.
To switch accounts later, type /login inside a running session.
Your First Session
Once you’re in, try asking about the project before asking it to change anything:
what does this project do?
Then something small:
add a hello world function to the main file
Claude Code will find the right file, show you the proposed change, and — depending on your permission mode — ask before writing. Press Shift+Tab to cycle permission modes: the default asks before each change, acceptEdits auto-approves file edits, and plan lets it propose without editing anything.
A few commands worth knowing on day one:
| Command | What it does |
|---|---|
claude | Start an interactive session |
claude "task" | Run a one-off task |
claude -p "query" | Run a query and exit (useful in scripts) |
claude -c | Continue the most recent conversation |
claude -r | Resume a previous conversation |
/help | List available commands |
/clear | Clear conversation history |
/exit | Quit |
Common Problems and Fixes
command not found: claude after installing. Your shell can’t find the binary. On macOS and Linux, the native installer puts it at ~/.local/bin/claude — make sure that directory is on your PATH. Opening a fresh terminal window often resolves it, since your shell config is re-read on startup.
Install fails with syntax error near unexpected token '<' or a 403. The download returned an error page instead of a script. This is usually a network or proxy issue. Check that your network can reach claude.ai, then retry.
Windows: The token '&&' is not a valid statement separator. You’re in PowerShell but ran the CMD command. Use irm https://claude.ai/install.ps1 | iex instead.
Windows: 'irm' is not recognized. You’re in CMD but ran the PowerShell command. Use the curl ... install.cmd version.
Search doesn’t work. Claude Code bundles ripgrep, but on Alpine and other musl-based distributions you need to install it separately and set USE_BUILTIN_RIPGREP to 0 in your settings.
npm install finishes but claude is missing. npm delivers the binary through a per-platform optional dependency. If your package manager is configured to skip optional dependencies, the binary never lands. Re-run with optional dependencies enabled.
Permission errors during npm install. Don’t reach for sudo. Reconfigure your npm global directory to somewhere you own.
Keeping It Updated
Native installs update themselves in the background and take effect next time you start. To force it:
claude update
Homebrew, WinGet, apt, dnf, and apk installs don’t auto-update — use those tools’ own upgrade commands.
You can control which channel you follow by setting autoUpdatesChannel in your settings file to "latest" (default, new features immediately) or "stable" (about a week behind, skips releases with major regressions).
Uninstalling
Native (macOS, Linux, WSL):
rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude
Homebrew: brew uninstall --cask claude-code
WinGet: winget uninstall Anthropic.ClaudeCode
npm: npm uninstall -g @anthropic-ai/claude-code
To also remove your settings, history, and MCP configuration, delete ~/.claude and ~/.claude.json. Be aware this is irreversible — and if you still have the VS Code extension, JetBrains plugin, or desktop app installed, the directory gets recreated next time one of them runs.
Where to Go Next
Now that it’s installed, the useful next step is learning to give it good instructions — that’s where most of the difference between a frustrating session and a productive one comes from.
Related reading:
- Claude Code vs Cursor — which tool fits your workflow
- Anthropic Claude review
- Best AI coding tools for beginners
- Official Claude Code documentation