The package is @anthropic-ai/claude-code: npm install -g @anthropic-ai/claude-code. It needs Node.js 22 or later as of v2.1.198, and it installs the same native binary the standalone installer does, pulled in as a per-platform optional dependency and linked into place by a postinstall script. The installed claude never invokes Node at runtime. Use npm when you need an explicit pinned version, as in CI, a container image, or behind a corporate registry. Prefer the native installer everywhere else.
- The package is
@anthropic-ai/claude-code. Node.js 22 or later as of v2.1.198. - It ships the same native binary as the installer script. Node is not used at runtime.
- Never
sudo npm install -g. The documented fix for EACCES is the native installer. - Upgrade with
@latest.npm update -grespects the original semver range and may not move you. --ignore-scriptsor--omit=optionalleaves a placeholder, not a binary.- npm is the right route for pinned versions in CI, containers, and air-gapped builds.
What the package actually is
This is the part that makes everything else make sense. @anthropic-ai/claude-code is a thin meta package. The real payload is a per-platform optional dependency such as @anthropic-ai/claude-code-darwin-arm64, and a postinstall step copies that binary into place as the claude command. Until postinstall runs, claude is a placeholder script.
The consequences, all of which surprise someone.
| Because | This follows |
|---|---|
| The payload is a native binary | Your Node version does not affect Claude Code at runtime |
| It arrives as an optional dependency | --omit=optional means no binary, and no JavaScript fallback |
| A postinstall script links it | --ignore-scripts leaves the placeholder in place |
| Binaries are per platform | A private registry must mirror all eight platform packages |
| The binary is identical to the script install | Switching install methods changes nothing about behaviour |
Installing it
node --version # 22 or later, as of v2.1.198
npm install -g @anthropic-ai/claude-code
claude --version
# 2.1.211 (Claude Code)
claude doctorThe two failures that look like bugs
One: the Node upgrade that hides the command
Claude Code worked for weeks, you upgraded Node, and now the command is not found. Nothing is corrupted. The binary is still there, under the previous Node version's global prefix, which is no longer on your PATH.
which -a claude # nothing, or an unexpected path?
npm root -g # where global packages live NOW
ls $(npm root -g) # is claude-code there?
nvm ls # if you use nvm, the old prefix is under the old versionTwo: the placeholder that was never replaced
This one has an exact error string, which makes it the easiest failure on the site to identify. On macOS and Linux, running claude prints:
Error: claude native binary not installed.
Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).
Run the postinstall manually (adjust path for local vs global install):
node node_modules/@anthropic-ai/claude-code/install.cjs
Or reinstall without --ignore-scripts / --omit=optional.On Windows you get no such message: bin/claude.exe is that same shell-script placeholder rather than a real executable, so PowerShell or CMD simply reports that it cannot run the file.
Work through these in order.
| Cause | Check | Fix |
|---|---|---|
| Optional dependencies disabled | --omit=optional, pnpm --no-optional, yarn --ignore-optional, or optional=false in .npmrc | Remove it and reinstall. Re-running install.cjs cannot place a binary that was never downloaded. |
| Install scripts disabled | --ignore-scripts, or a pnpm config that skips postinstall | node node_modules/@anthropic-ai/claude-code/install.cjs, or reinstall without the flag |
| Unsupported platform | Your platform is not one of the eight published targets | Use a supported platform. On FreeBSD the installer now reports it as unsupported rather than downloading a Linux binary that cannot run. |
| Corporate registry mirror | Only the meta package is mirrored | Mirror all eight @anthropic-ai/claude-code-* platform packages too |
When npm is the right answer
| Situation | Why npm wins |
|---|---|
| CI pipelines | An exact version, expressed the same way as the rest of your lockfile discipline |
| Docker images | One layer, no installer script, no shell profile to source |
| Corporate registries | Route through an internal npm mirror you already trust |
| Air-gapped environments | Vendor the tarballs and install offline |
| You need a specific old version | Version selection is explicit and obvious in review |
# exact version
npm install -g @anthropic-ai/claude-code@2.1.89
# what is available
npm view @anthropic-ai/claude-code versions --json | tail -20
# what you have
claude --versionUpdating and removing
# correct
npm install -g @anthropic-ai/claude-code@latest
# or let Claude Code do it, on any install type
claude update
# remove
npm uninstall -g @anthropic-ai/claude-code
# settings and history live outside the package
# ~/.claude/ config, memory, sessions, skills
# ~/.claude.json account stateSwitching to the native install
If you are on npm for no particular reason, this is a five-command change with nothing at stake.
curl -fsSL https://claude.ai/install.sh | bash
exec $SHELL -l
which -a claude # native one should be first
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local # legacy local install, if present
claude doctorQuestions people ask
@anthropic-ai/claude-code. Install it globally with npm install -g @anthropic-ai/claude-code. It requires Node.js 22 or later as of v2.1.198, though an older Node produces a warning rather than a failure.
No. The npm package delivers a per-platform native binary through an optional dependency, and a postinstall step links it into place. The installed claude command does not invoke Node at runtime, which is why your Node version does not affect it once it is installed.
The native installer for a personal machine: it is self-contained, self-updating, and unaffected by Node upgrades. npm when you need an npm-shaped supply chain, such as a corporate registry, an air-gapped build, or a container image you already build with npm.
A global npm install lives under the Node version prefix that was active at install time. Upgrading Node changes the prefix, so the command is no longer on PATH. Reinstall under the current Node, or move to the native installer, which is unaffected by Node entirely.
Do not use sudo, which creates root-owned files that break later installs. The documented fix is to switch to the native installer with curl -fsSL https://claude.ai/install.sh | bash, which installs entirely under your home directory.
The postinstall step was skipped, usually by --ignore-scripts or a pnpm config, or the platform optional dependency was never downloaded, usually by --omit=optional. Reinstall without those flags. Re-running install.cjs cannot help if the binary was never downloaded.
Yes: npm install -g @anthropic-ai/claude-code@2.1.89. The native installer also accepts a version or a channel, as in curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89, so pinning alone is no longer a reason to prefer npm.
No. Configuration, project memory, skills, and session history live in ~/.claude/ and ~/.claude.json, outside the package, and survive uninstalling. They also reappear if the VS Code extension, JetBrains plugin, or desktop app is still installed.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.