Claude Code installs from a single command on every supported platform, and the whole first run is: install, type claude, log in. This guide has the exact command for each OS, what to check when it doesn't work, and how to point it at a different endpoint once it does.
Commands verified September 4, 2026 against Anthropic's Claude Code setup documentation.
Before you start
| Requirement | What's supported |
|---|---|
| Operating system | macOS 13.0+, Windows 10 1809+ / Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+ |
| Hardware | 4 GB+ RAM, x64 or ARM64 |
| Shell | Bash, Zsh, PowerShell or CMD |
| Network | Internet connection required |
| Account | Pro, Max, Team, Enterprise or Console — the free Claude.ai plan does not include Claude Code |
Install — the native installer
This is the recommended method on every platform. It installs a self-contained binary and keeps itself updated in the background.
# 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.cmdIf you aren't sure which Windows shell you're in, the prompt tells you: PowerShell shows PS C:\, CMD shows C:\ without the PS. Running the wrong one is the single most common install failure on Windows — see the troubleshooting table below for the exact error each way round.
Package managers
Use these if you'd rather your existing package manager own the install. The trade-off is updates: none of these auto-update by default, unlike the native installer.
# Homebrew (macOS, Linux) — stable channel
brew install --cask claude-code
# WinGet (Windows)
winget install Anthropic.ClaudeCode
# npm — requires Node.js 22+; never with sudo
npm install -g @anthropic-ai/claude-codeHomebrew publishes two casks: claude-code tracks the stable channel (typically about a week behind, skipping releases with major regressions) and claude-code@latest ships every release immediately. Signed apt, dnf and apk repositories exist for Debian / Ubuntu, Fedora / RHEL and Alpine, each with the same stable and latest channels.
On npm, never use sudo npm install -g — it causes permission problems and is a security risk. The npm package installs exactly the same native binary as the standalone installer, so there is no runtime Node dependency either way.
Verify the install
claude --version # prints e.g. "2.1.211 (Claude Code)"
claude doctor # read-only install + settings diagnostics
claude # start a session in the current projectclaude doctor is the one to remember: it prints install health, settings-file validation errors and suggested fixes without starting a session, which makes it the fastest way to tell a broken install from a broken config.
First run and login
Open a terminal in the project you want to work in and run claude. It opens an interactive session and walks you through login in the browser. Claude Code requires a Pro, Max, Team, Enterprise or Console account.
One behaviour worth knowing before it surprises you: if ANTHROPIC_API_KEY is already set in your environment, Claude Code prompts you once to approve that key instead of opening a browser. Decline that prompt and the key is silently ignored from then on with no further prompt — which looks exactly like the variable not being read. Re-enable it under /config → Use custom API key.
Windows: native or WSL
| Option | Requires | Sandboxing | Pick it when |
|---|---|---|---|
| Native Windows | Nothing; Git for Windows optional | Not supported | Your projects and tools are Windows-native |
| WSL 2 | WSL 2 enabled | Supported | Linux toolchains, or you want sandboxed command execution |
| WSL 1 | WSL 1 enabled | Not supported | WSL 2 isn't available to you |
On native Windows, installing Git for Windows is optional but recommended: it provides the Git Bash that backs the Bash tool. Without it, Claude Code runs shell commands through the PowerShell tool instead. Under WSL you install and launch claude inside the WSL terminal, not from PowerShell.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
The token '&&' is not a valid statement separator | You ran the CMD command in PowerShell. Use the irm … | iex line instead. |
'irm' is not recognized… | The reverse — you ran the PowerShell command in CMD. Use the curl … install.cmd line. |
syntax error near unexpected token '<', a 403, or another curl error | The download didn't return the script — usually a proxy or a network filter between you and the installer. Retry, or use a package-manager install instead. |
claude: command not found after a clean install | Open a new terminal so your shell picks up the install directory, then run claude doctor. A second, older install or a stale shell alias is the other common cause. |
| Permission errors during an npm install | You used sudo, or the npm global directory isn't writable. Fix the directory ownership rather than re-running with sudo; an unwritable global directory also blocks auto-update. |
Native binary missing after npm install -g | Your package manager is configured to skip optional dependencies. The platform binary ships as one, so allow them and reinstall. |
| Install fails on Alpine or another musl distro | Alpine ships without bash and curl. Install bash curl libgcc libstdc++ ripgrep, then set USE_BUILTIN_RIPGREP to "0" in the env block of your settings file. |
| Search and file discovery fail | ripgrep is normally bundled. If it can't run on your platform, install the system ripgrep and set USE_BUILTIN_RIPGREP=0. |
| Bash tool missing on native Windows | Install Git for Windows. If Claude Code still can't find Git Bash, set CLAUDE_CODE_GIT_BASH_PATH in the env block of ~/.claude/settings.json. |
401 once a key is configured | The key is in the header the server doesn't read — swap between ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY. Details in the API key guide. |
Pointing Claude Code at Kunavo
Once it runs, Claude Code will work against any endpoint that serves the Anthropic Messages API — it reads ANTHROPIC_BASE_URL natively, so this is a supported configuration rather than a workaround. No plugin, no proxy, no patched binary:
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5Four things about that block, each of which will cost you an hour if you get it wrong:
ANTHROPIC_BASE_URLis the origin only. Claude Code appends/v1/messagesitself — including the path yields a 404.- Use
ANTHROPIC_AUTH_TOKEN, notANTHROPIC_API_KEY. They go in different HTTP headers. The bearer token takes effect immediately, whileANTHROPIC_API_KEYneeds the one-time approval described above — and on Kunavo the bearer header is also what makes model discovery work, since/v1/modelsreads it and nothing else. - Set
ANTHROPIC_MODELexplicitly. Kunavo matches model slugs exactly and does not alias date-suffixed names, soclaude-sonnet-4-5-20250929returns 404 whereclaude-sonnet-4-6works. ANTHROPIC_DEFAULT_HAIKU_MODELcovers the background calls Claude Code makes on its own for summaries and titles.claude-haiku-4-5is $0.40 / $2.00 per 1M against $1.20 / $6.00 for the mainline model, so it's one line for a permanent saving.
Put these in the env block of ~/.claude/settings.json rather than a shell export if you want editors and background agents to see them too — and never in a project's committed .claude/settings.json. Create the sk-kn- key in the dashboard after signing up; a $10 top-up is the minimum, there's no monthly fee and the balance doesn't expire. What each model costs per token, against Anthropic's official API pricing, decides how far that $10 goes.
What changes behind a gateway
Coding, tools, subagents, MCP, hooks and prompt caching are all unaffected. Three things do change, and they're worth knowing before you assume something is broken:
- Remote Control and voice dictation are unavailable. Both need a claude.ai identity, which a gateway credential replaces.
/fastmay report fast mode as disabled. The availability check calls Anthropic directly rather than following your base URL. Normal requests are unaffected./contextcounts become local estimates. Token counting is the one endpoint Anthropic's own gateway specification marks optional, and Claude Code estimates locally when it is absent — Kunavo does not serve/v1/messages/count_tokenstoday. Auto-compaction and the session itself are unaffected.
The full list, plus the router-versus-no-router decision, is in the Claude Code router guide.
FAQ
How do I install Claude Code?
On macOS, Linux or WSL run `curl -fsSL https://claude.ai/install.sh | bash`. On Windows run `irm https://claude.ai/install.ps1 | iex` in PowerShell, or `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` in CMD. The native installer is the recommended method and keeps itself updated in the background. Homebrew (`brew install --cask claude-code`), WinGet (`winget install Anthropic.ClaudeCode`), npm and signed apt/dnf/apk repositories are also supported, but none of those auto-update by default.
Do I need Node.js to install Claude Code?
Not for the native installer, Homebrew, WinGet or the Linux package repositories — all of them install a native binary that does not use Node at runtime. Only the npm install path involves Node, and as of v2.1.198 that package requires Node.js 22 or later. Even then npm just pulls in the same native binary through a per-platform optional dependency.
What are the system requirements for Claude Code?
macOS 13.0+, Windows 10 1809+ or Windows Server 2019+, Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+; 4 GB or more of RAM on an x64 or ARM64 processor; an internet connection; and Bash, Zsh, PowerShell or CMD as the shell. You must also be in a country Anthropic supports.
How do I log in to Claude Code the first time?
Run `claude` in a project directory and follow the browser prompts. Claude Code requires a Pro, Max, Team, Enterprise or Console account — the free Claude.ai plan does not include Claude Code access. If the ANTHROPIC_API_KEY environment variable is set, Claude Code prompts you once to approve that key instead of opening a browser.
Can I install Claude Code on Windows without WSL?
Yes. Run the PowerShell or CMD installer and launch `claude` from any terminal; you do not need Administrator rights. Git for Windows is optional but recommended, because it provides the Git Bash that backs the Bash tool — without it Claude Code runs shell commands through the PowerShell tool instead. WSL 2 is the option to pick if you want Linux toolchains or sandboxed command execution, which native Windows does not support.
Why does `claude` say command not found after installing?
The install directory is not on your PATH in the shell you are using. Open a new terminal first — the installer adds ~/.local/bin on macOS and Linux, and an existing session will not pick that up. Run `claude doctor` for read-only diagnostics of the install and your settings files. A second, older installation or a leftover shell alias is the other common cause.
How do I point Claude Code at a different API endpoint?
Set ANTHROPIC_BASE_URL to the origin of any endpoint that serves the Anthropic Messages API — Claude Code reads it natively and appends /v1/messages itself, so no plugin or proxy is involved. Pair it with ANTHROPIC_AUTH_TOKEN for the credential and an explicit ANTHROPIC_MODEL. On Kunavo that runs the same Claude models at 30–60% under Anthropic's list price, pay-as-you-go.
Next steps
- Claude Code API key — where to get one, where to put it, and the header mismatch behind most 401s.
- Claude Code pricing — subscription versus API, per-model rates, and what a month costs.
- Is Claude Code free? — what's free, what isn't, and where the line sits.
- Running it without permission prompts — what
--dangerously-skip-permissionsactually removes, and three containments that take about a minute each. - Claude Code vs Codex CLI — if you're still choosing a terminal agent.