npm install Claude Code: Complete Package Installation Guide (2026)

Prerequisites

The npm installation requires two things: Node.js and a paid Anthropic account.

Node.js 18.0+

The package is distributed as an ES module. Node.js versions below 18 will install the package without errors but fail at runtime with a syntax error. Always verify your version first:

node --version    # Must be v18.0.0 or higher
npm --version     # Any recent npm works (v8+)

If your Node.js is too old, use nvm to install a current version:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Install and use Node.js 22 (LTS)
nvm install 22
nvm use 22

# Verify
node --version   # v22.x.x

Anthropic Account

Claude Code requires a paid account. Any of these work: Claude Pro ($20/month), Claude Max ($100-200/month), Claude Teams, Claude Enterprise, or an Anthropic Console account with API credits. The free Claude.ai plan does not include Claude Code access.

Install Command

One command installs Claude Code globally and makes the claude CLI available everywhere:

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

After installation, verify it worked:

claude --version   # Should print the installed version
which claude       # Shows the install location

Global vs Local Install

Global Install (Recommended)

The -g flag installs Claude Code system-wide. The claude command becomes available in every terminal session, in every directory.

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

# Available everywhere
cd ~/project-a && claude    # works
cd ~/project-b && claude    # works

Local Install (Per-Project)

You can install Claude Code as a project dependency. This is useful for locking the version per-project or for monorepo setups where different teams need different versions.

# Install as a dev dependency
npm install --save-dev @anthropic-ai/claude-code

# Run via npx from the project root
npx claude

# Or add to package.json scripts
# "scripts": { "claude": "claude" }
npm run claude

Fixing Permission Errors

EACCES permission errors are the most common npm installation issue. They happen when npm tries to write to a directory your user doesn't own (typically /usr/local/lib/node_modules).

Fix 1: Change npm's Default Directory

# Create a new directory for global packages
mkdir -p ~/.npm-global

# Tell npm to use it
npm config set prefix '~/.npm-global'

# Add to your shell profile (~/.zshrc, ~/.bashrc, or ~/.profile)
export PATH=~/.npm-global/bin:$PATH

# Reload your shell
source ~/.zshrc   # or source ~/.bashrc

# Now install without permission issues
npm install -g @anthropic-ai/claude-code

Fix 2: Use nvm (Recommended)

nvm installs Node.js in your home directory, so global npm installs never need elevated permissions.

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Install Node.js
nvm install 22

# Install Claude Code (no permission issues)
npm install -g @anthropic-ai/claude-code

Version Management

Install a Specific Version

# Install exact version
npm install -g @anthropic-ai/claude-code@2.1.74

# Check available versions
npm view @anthropic-ai/claude-code versions --json

# Check latest version
npm view @anthropic-ai/claude-code version

Update to Latest

# Update to latest
npm update -g @anthropic-ai/claude-code

# Or reinstall to force latest
npm install -g @anthropic-ai/claude-code@latest

# Check current version
claude --version

Downgrade

If a new version introduces a regression, pin back to a working release:

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

Alternative Package Managers

npx (Run Without Installing)

npx downloads and runs the package in one step. No global install, no cleanup needed.

# Run latest version without installing
npx @anthropic-ai/claude-code

# Run a specific version
npx @anthropic-ai/claude-code@2.1.74

bunx (Bun)

If you use Bun as your JavaScript runtime, bunx is the equivalent of npx:

# Run without installing
bunx @anthropic-ai/claude-code

# Or install globally with Bun
bun install -g @anthropic-ai/claude-code

yarn

# Yarn 1.x global install
yarn global add @anthropic-ai/claude-code

# Yarn 2+ (Berry) - use dlx for one-off execution
yarn dlx @anthropic-ai/claude-code

pnpm

# Global install
pnpm add -g @anthropic-ai/claude-code

# One-off execution
pnpm dlx @anthropic-ai/claude-code

Post-Install Setup

Step 1: Authenticate

Run claude in any project directory. On first launch, it opens your browser for OAuth authentication.

cd your-project
claude

# Browser opens -> authorize Claude Code -> token stored locally

For headless environments (CI, SSH, containers), set an API key instead:

export ANTHROPIC_API_KEY=sk-ant-...
claude   # Skips browser auth, uses API key directly

Step 2: Generate CLAUDE.md

CLAUDE.md is the most important post-install configuration. It gives Claude persistent context about your project: build commands, conventions, architecture decisions.

# Inside Claude Code, run:
/init

# This analyzes your codebase and generates a CLAUDE.md with:
# - Detected build system and commands
# - Test framework configuration
# - Code style patterns
# - Project structure overview

Step 3: Verify Everything Works

# Check version
claude --version

# Check health
claude doctor

# Check authentication
claude whoami

Installing MCP Servers Alongside Claude Code

MCP (Model Context Protocol) servers extend Claude Code with external tools. After installing Claude Code via npm, you can add MCP servers that give Claude access to search, databases, GitHub, and other services.

# Add WarpGrep for RL-trained code search
claude mcp add warpgrep -- npx -y warpgrep-mcp@latest

# Add GitHub integration
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Add an HTTP-based MCP server
claude mcp add notion --transport http https://mcp.notion.com/mcp

# List all configured servers
claude mcp list

Common Errors and Fixes

npm ERR! EACCES: permission denied

npm is trying to write to a root-owned directory. See the Permission Errors section above. Never use sudo.

SyntaxError: Cannot use import statement outside a module

Your Node.js version is below 18. The package uses ES module syntax that older Node versions don't support.

node --version          # Check current version
nvm install 22          # Install Node 22
nvm use 22              # Switch to it
npm install -g @anthropic-ai/claude-code   # Reinstall

npm ERR! code ENOENT or network errors behind a proxy

Corporate proxies and firewalls can block npm registry access. Configure npm to use your proxy:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# If using a custom registry
npm config set registry https://registry.company.com/

# Then retry
npm install -g @anthropic-ai/claude-code

claude: command not found after npm install

The npm global bin directory isn't in your PATH. Find it and add it:

# Find npm's global bin directory
npm bin -g

# Add it to your PATH in ~/.zshrc or ~/.bashrc
export PATH=$(npm bin -g):$PATH

# Reload shell
source ~/.zshrc

npm WARN deprecated warnings during install

Deprecation warnings from transitive dependencies are harmless. The package will still install and work correctly. These warnings come from sub-dependencies, not from Claude Code itself.

WSL: Node.js installed on Windows but not in WSL

If you're using WSL, you need Node.js installed inside the WSL environment, not just on the Windows side. Install nvm inside WSL and set up Node.js there.

npm Install vs Native Installer

Anthropic offers multiple installation methods. Here's when to use npm vs the alternatives:

For most developers, the native installer is the better default. Use npm when you have a specific reason: pinning versions in CI, standardizing on npm across your team, or installing as a local project dependency.

Frequently Asked Questions

What is the npm command to install Claude Code?

npm install -g @anthropic-ai/claude-code. This installs the claude CLI globally. Requires Node.js 18.0 or newer.

Do I need Node.js to use Claude Code?

Only for the npm installation method. The native installer and Homebrew methods have zero dependencies. Use those if you don't want to manage a Node.js installation.

How do I fix EACCES permission errors?

Never use sudo. Either reconfigure npm's global directory (npm config set prefix '~/.npm-global') or use nvm, which installs Node.js in your home directory and avoids permission issues entirely.

Can I use npx instead of installing globally?

Yes. npx @anthropic-ai/claude-code downloads and runs Claude Code in one step without a permanent install. bunx @anthropic-ai/claude-code works the same way for Bun users.

How do I update Claude Code installed via npm?

Run npm update -g @anthropic-ai/claude-code. Or force the latest: npm install -g @anthropic-ai/claude-code@latest. Check your current version with claude --version.

Should I use npm or the native installer?

The native installer is better for daily use: zero dependencies, auto-updates. Use npm if you need version pinning (CI/CD), per-project installs, or your team standardizes on npm for CLI tool management.

What Node.js version does Claude Code require?

Node.js 18.0 or newer. The package is an ES module; older Node versions fail at runtime with syntax errors. Use node --version to check, and nvm to upgrade.

What is the exact npm package name?

@anthropic-ai/claude-code. It's published under Anthropic's npm scope (@anthropic-ai). The full install command is npm install -g @anthropic-ai/claude-code.

Related Guides

• Install Claude Code: All Methods (Native, Brew, npm, Windows)
• CLAUDE.md Guide: Configure Claude Code for Your Project
• Claude Code vs Cursor
• Claude Code vs GitHub Copilot