ModelsPricingDocsGuidesUse casesCompareAbout
Log inGet started
Back to guides
Setup·August 5, 2026·8 min read

Install Claude Code — the command for every OS, first login, and the errors people hit

Installing Claude Code is one command on every platform. Here is that command for each OS, what to run when it doesn't work, and the four environment variables that put it on a different endpoint afterwards.

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 August 5, 2026 against Anthropic's Claude Code setup documentation.

Before you start

RequirementWhat's supported
Operating systemmacOS 13.0+, Windows 10 1809+ / Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
Hardware4 GB+ RAM, x64 or ARM64
ShellBash, Zsh, PowerShell or CMD
NetworkInternet connection required
AccountPro, 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.

install.sh
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
PowerShell
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
cmd.exe
:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

If 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.

package-managers.sh
# 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-code

Homebrew 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

verify.sh
claude --version   # prints e.g. "2.1.211 (Claude Code)"
claude doctor      # read-only install + settings diagnostics
claude             # start a session in the current project

claude 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

OptionRequiresSandboxingPick it when
Native WindowsNothing; Git for Windows optionalNot supportedYour projects and tools are Windows-native
WSL 2WSL 2 enabledSupportedLinux toolchains, or you want sandboxed command execution
WSL 1WSL 1 enabledNot supportedWSL 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

SymptomCause and fix
The token '&&' is not a valid statement separatorYou 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 errorThe 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 installOpen 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 installYou 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 -gYour 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 distroAlpine 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 failripgrep 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 WindowsInstall 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 configuredThe 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:

~/.zshrc
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-5

Four things about that block, each of which will cost you an hour if you get it wrong:

  • ANTHROPIC_BASE_URL is the origin only. Claude Code appends /v1/messages itself — including the path yields a 404.
  • Use ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY. They go in different HTTP headers. The bearer token takes effect immediately, while ANTHROPIC_API_KEY needs the one-time approval described above — and on Kunavo the bearer header is also what makes model discovery work, since /v1/models reads it and nothing else.
  • Set ANTHROPIC_MODEL explicitly. Kunavo matches model slugs exactly and does not alias date-suffixed names, so claude-sonnet-4-5-20250929 returns 404 where claude-sonnet-4-6 works.
  • ANTHROPIC_DEFAULT_HAIKU_MODEL covers the background calls Claude Code makes on its own for summaries and titles. claude-haiku-4-5 is $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 $5 top-up is the minimum, there's no monthly fee and the balance doesn't expire.

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.
  • /fast may report fast mode as disabled. The availability check calls Anthropic directly rather than following your base URL. Normal requests are unaffected.
  • /context counts 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_tokens today. 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.

Next steps