Installing Claude via npm | Avoiding sudo and Updating with @latest

Claude Code Is Available via npm — The Official Node.js Installation Path

Claude Code (the claude command) is distributed as Anthropic's official npm package @anthropic-ai/claude-code. In any environment with Node.js 18 or later, you can install it with npm install -g @anthropic-ai/claude-code source. The npm path is ideal for teams already running Node.js projects — it adds no extra setup steps and can be reproduced consistently in any environment where node is available, such as CI pipelines or Docker images.

One important thing to understand: the npm package is not a JavaScript CLI. What gets distributed is a wrapper around platform-native binaries. It pulls the binary via optional dependencies named with suffixes like darwin-arm64, then creates a link during post-install. Once installed, running claude does not call Node.js at all, so startup overhead is equivalent to the native installer.

In short, the npm path uses npm as a distribution channel, but the actual executable is a native binary — the same binary you'd get from Homebrew or WinGet. The only differences are how updates are automated and where the binary ends up in your PATH.

System Requirements — Node.js 18+ and 8 Supported Platforms

The minimum requirements for npm installation are as follows source:

• Node.js: 18 or later (LTS recommended)
• OS: macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+ / Alpine Linux 3.19+
• RAM: 4 GB or more
• Subscription: Claude Pro, Max, Team, Enterprise, or Anthropic Console

Anthropic pre-builds and distributes native binaries for 8 platforms: darwin-arm64 (Apple Silicon Mac), darwin-x64 (Intel Mac), linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, and win32-arm64 — covering everything from Apple Silicon Macs to ARM64 Windows. Platforms outside these 8 (e.g., 32-bit Raspberry Pi OS, or Intel/AMD CPUs from before 2013 that lack AVX instructions) are not supported.

Subscription requirements apply equally on the npm path — a free Claude.ai plan will not pass authentication. Check your billing account status at claude.ai/settings before installing to avoid running into a 403 Forbidden error after setup.

Installation Command and First-Time Authentication — From npm install to Launching claude

The actual installation is a one-liner source:

npm install -g @anthropic-ai/claude-code

Do not assume success just because the command exits without errors. As covered later in this article, cases like "Native binary not found" can cause the install to appear successful while the launch fails. Always verify by checking the version number first:

claude --version
# Expected output example (replace with actual version)
# 2.0.14 (Claude Code)

If a version number appears, the native binary is correctly linked. Then run claude from any project directory to proceed with first-time setup. Claude will open a browser window and redirect you to OAuth login. In SSH, WSL2, or Docker environments where the browser does not open automatically, press c at the interactive prompt to copy the OAuth URL to your clipboard, then open it in a local browser.

When working on a remote host, the browser redirects to your local machine — after logging in, paste the displayed code manually to complete authentication. If pasting does not work, use claude auth login, which reads the code from standard input and avoids clipboard inconsistencies.

After logging in, run claude doctor once to diagnose your PATH, Keychain, Node.js version, and network connectivity all at once. Running this immediately after installation helps catch any first-time issues before they become problems.

Why Not to Use sudo — Keep Node.js in User Space with nvm or Volta

The most common mistake on the npm path is running sudo npm install -g @anthropic-ai/claude-code. Anthropic explicitly states that you must not use sudo, as installing into root-owned directories leads to permission corruption, security risks, and privilege mismatches in subsequent commands source.

The solution is to manage Node.js itself with a user-space version manager. Common options include:

• nvm (Node Version Manager): Places Node under ~/.nvm, enabling -g installs without sudo. Install with a single curl command (official: github.com/nvm-sh/nvm)
• Volta: A fast Rust-based Node manager with strong per-project version pinning
• asdf + nodejs plugin: Useful for managing versions across multiple languages

Regardless of which you choose, if which node points to somewhere under your home directory (e.g., ~/.nvm/versions/node/...) rather than /usr/bin/node or /usr/local/bin/node, then npm install -g will work without sudo. If you are currently using a system-wide Node.js installation under /usr/local, the safest long-term approach is to uninstall it and switch to nvm or a similar tool.

If a previous sudo-installed @anthropic-ai/claude-code is still present and causing permission errors, remove it first with sudo npm uninstall -g @anthropic-ai/claude-code, then reinstall as a regular user.

Updating with @latest — Why npm update -g Does Not Work

Claude Code receives frequent updates (roughly weekly), making regular updates effectively mandatory. The only correct approach for updating via npm is source:

npm install -g @anthropic-ai/claude-code@latest

A common mistake is running npm update -g. Anthropic explicitly advises against using npm update -g because the update command respects the semver range from the original install, which may not reach the latest available version.

In practice, it helps to create an alias or shell function in your .zshrc / .bashrc to ensure you always use @latest:

claude-up() {
  npm install -g @anthropic-ai/claude-code@latest
  claude --version
}

Always confirm the version number with claude --version after updating to verify it incremented as expected. On Windows, if the Claude Desktop app left behind an old Claude.exe in WindowsApps, it may take precedence in PATH — the --version check is the only way to catch this.

Enabling Auto-Update — CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1

The native installer path runs background auto-updates automatically, but auto-update is disabled by default on the npm path source. While Homebrew and WinGet support auto-update via the CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 environment variable, this flag does not enable auto-update for npm. This is because npm has no mechanism for running persistent background processes.

When using npm, you must choose one of the following approaches:

• Manual update: Run npm install -g @anthropic-ai/claude-code@latest weekly or biweekly
• cron / Scheduled Task: Register the above command as a recurring scheduled job (no restart required)
• Switch paths: If auto-update is essential, migrate to the native installer

For CI or Docker use cases, specifying npm install -g @anthropic-ai/claude-code@latest in your Dockerfile ensures the latest version is always installed at image build time — making auto-update irrelevant.

Native Binary Not Found — The optionalDependencies Trap and Corporate Registries

A common issue is that npm install -g @anthropic-ai/claude-code appears to succeed, but launching claude fails with Could not find native binary package "@anthropic-ai/claude-code-<platform>" source. There are three root causes:

1. Optional dependencies are disabled: Check whether --omit=optional is passed to npm install, --no-optional to pnpm, or --ignore-optional to yarn. Also check if .npmrc contains optional=false — this silently disables optional dependencies.
2. Unsupported platform: No binary is distributed for platforms outside the 8 supported ones.
3. Incomplete corporate npm registry mirror: Even if the meta package is mirrored, installation fails if any of the 8 @anthropic-ai/claude-code-* platform packages are missing from the mirror.

Corporate users are especially likely to run into issue 3 — you will need to ask your IT/infrastructure team to mirror all 8 platform packages. Note that using --ignore-scripts skips the post-install linking step, causing Claude Code to fall back to a wrapper mode that searches for the binary at launch time. This works but is slower to start — reinstall without --ignore-scripts if possible.

WSL npm Pitfalls — Conflicts with Windows nvm

When developing on Windows + WSL2, there are three npm-specific traps to watch out for source:

1. WSL picks up Windows npm: Set npm config set os linux to explicitly declare the OS, then reinstall with npm install -g @anthropic-ai/claude-code --force
2. exec: node: not found: If which npm or which node returns a path starting with /mnt/c/, WSL is using the Windows Node. Install Node on the Linux side with nvm.
3. nvm conflicts between Windows and WSL: If NVM_DIR is not set in WSL's ~/.bashrc, Windows nvm takes precedence. Add the following block to .bashrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

If Windows paths still take priority, explicitly place the Linux Node binary at the front of PATH:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Using appendWindowsPath = false to completely strip the Windows PATH is not recommended, as it prevents calling Windows executables from WSL. Uninstalling Windows nvm is also best avoided to prevent breaking Windows-side Node development.

Uninstalling and Cleaning Up Old Local Installs

To remove Claude Code installed via npm source:

npm uninstall -g @anthropic-ai/claude-code

To completely remove configuration files as well, run the following on macOS or Linux:

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

One easy-to-miss issue is old Claude Code versions leaving behind a local npm install under ~/.claude/local/. This is a remnant of how older versions were distributed and can hijack PATH even after migrating to the native installer. Check with ls -la ~/.claude/local/ and remove with rm -rf ~/.claude/local if no longer needed.

On Windows, run Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local" in PowerShell. If which -a claude (macOS/Linux) or where.exe claude (Windows) shows multiple claude entries, remove the conflicting one before PATH priority causes confusion.

Comparing Installation Paths — Native, Homebrew, WinGet vs. npm

Here is a summary of when to choose the npm path versus the alternatives:

The npm path is best for: development machines already running Node.js, reproducible CI/Docker images, and teams managing dependencies primarily through npm. For personal use where you just want to get started, the native installer with auto-update is simpler to maintain — and it's what Anthropic lists first as the recommended path.

If you are unsure, use this decision flow:

1. Want to embed in CI / Docker / a Node project → npm
2. Personal PC (macOS / Windows) wanting auto-update → Native installer
3. Managing tools primarily through brew / winget → Homebrew / WinGet

For a cross-platform comparison of installation paths and general troubleshooting, see Installing Claude CLI. For Windows-specific path selection, Installing Claude on Windows is also worth reading to find the path that best fits your environment.