Installing Claude Code: Native vs npm, Fixing PATH, and First Run

For a Native Install of Claude Code, the Node.js runtime is not required at all. The npm installer currently requires Node.js 22+, but the installed binary itself runs completely independent of the Node runtime. Anthropic’s official documentation explicitly recommends using Native Install (for full details, see the installation guide). To work with the coding agent in your terminal, you need to choose an installation method, run the appropriate command in a supported shell, and ensure the executable is correctly recognized by your operating system. When command invocation errors arise, identifying the root cause depends on distinguishing between a native standalone distribution and a package manager install.

Native vs npm: Architectural Boundaries and the Role of Node.js

Anthropic’s official documentation recommends Native Install (installation guide). In this setup, the Node.js runtime is unnecessary: the installer downloads a precompiled standalone binary that never interacts with Node during execution.

Installing via the global npm package remains an available alternative. Currently, the npm installer requires Node.js 22 or higher. If you run the installation on an earlier Node.js version, npm will emit an EBADENGINE warning, but the process typically completes: the package pulls down a platform-specific precompiled binary and creates a symlink to it. At runtime, the installed Claude Code binary still does not execute inside Node.js.

Consequently, the claim that running Claude Code always requires Node.js is technically false. Checking your Node.js version is only necessary when you intentionally choose to install via npm.

Installation Commands for Supported Operating Systems

To ensure a proper setup, run the official script corresponding to your operating system and shell environment.

macOS, Linux, and WSL (Bash / Zsh)

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows Command Prompt (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Alternative Installation via npm

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

Important: Do not execute this command with sudo npm install -g. Running package installations with superuser privileges leads to file permission conflicts inside your home directory and introduces security risks.

On native Windows, installing Git for Windows is now optional. If Git for Windows is present, the agent can execute Bash commands via Git Bash; if it is not installed, Claude Code falls back to its built-in PowerShell tooling.

Verifying the Installation

Once the installer completes, verify that the binary is accessible in your environment:

claude --version

A correct version output confirms that the binary was downloaded, extracted, and registered in your environment. Note that a successful version display only verifies the binary itself; it does not indicate that the client is authenticated or capable of making model requests.

For a comprehensive environment audit, run the diagnostic utility:

claude doctor

The claude doctor command audits your local setup: it checks configuration files, filesystem permissions, and system dependencies, identifying potential configuration issues without starting an interactive coding session.

Troubleshooting: Resolving command not found Errors

If your terminal reports that claude is not found (or Windows displays an error stating that the command is not recognized as an internal or external command), follow this diagnostic workflow:

[Ошибка вызова: claude не найден]
         │
         ▼
[Шаг 1: Открыть новый сеанс терминала]
         │
    Помогло? ──Да──> Завершено
         │ Нет
         ▼
[Шаг 2: Проверить физическое наличие бинарного файла на диске]
         │
    Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку
         │ Да
         ▼
[Шаг 3: Проверить тип установки и PATH]
         │
 ┌───────┴────────────────────────┐
 ▼                                ▼
[Native Install]                [npm Install]
Проверить PATH:                 Проверить PATH через npm prefix -g:
- Unix: ~/.local/bin            - Unix: <prefix>/bin
- Win: %USERPROFILE%\.local\bin - Win: <prefix>
(Не переустанавливать только из-за PATH)

The decision tree above maps out the diagnostic progression:

• Root error: [Ошибка вызова: claude не найден] translates to [Invocation error: claude not found].
• Step 1: [Шаг 1: Открыть новый сеанс терминала] asks you to open a new terminal session. If that resolved the issue (Помогло? ──Да──> Завершено / Did it help? ──Yes──> Completed), you are done. If not (Нет / No), proceed to Step 2.
• Step 2: [Шаг 2: Проверить физическое наличие бинарного файла на диске] checks for the binary file on disk. If absent (Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку / File found? ──No──> Download/permission error; reinstall), re-run the installation script. If present (Да / Yes), proceed to Step 3.
• Step 3: [Шаг 3: Проверить тип установки и PATH] evaluates your installation method and PATH variables:
  • For Native Install, check PATH (Проверить PATH:): ~/.local/bin on Unix or %USERPROFILE%\.local\bin on Windows.
  • For npm Install, check PATH via npm prefix -g (Проверить PATH через npm prefix -g:): <prefix>/bin on Unix or <prefix> on Windows.
  • The reminder at the bottom (Не переустанавливать только из-за PATH) cautions: (Do not reinstall solely because of PATH issues).

1. Open a New Terminal Session

Installation scripts modify your shell profile (.bashrc, .zshrc) or Windows user environment variables. Existing terminal sessions do not pick up these modifications on the fly. Close your current terminal window completely and open a fresh session.

2. Verify the Physical Binary Path

With Native Install, the executable is placed in standard default directories (unless overridden by custom environment settings):

• On macOS, Linux, and WSL: ~/.local/bin/claude (versioned packages reside in ~/.local/share/claude).
• On Windows: %USERPROFILE%\.local\bin\claude.exe.

These paths are defaults, not unchangeable locations if user overrides are in effect. If the file is absent from the expected directory, the installer may have failed prematurely due to a network interruption or insufficient write permissions.

3. Run Shell Diagnostic Commands

To determine whether and how your shell discovers the executable, use native inspection tools:

• In Zsh / Bash: run command -v claude or type -a claude.
• In PowerShell: run Get-Command claude and where.exe claude.
• In CMD: run where claude.

4. Separate PATH Resolution for Native and npm

A common diagnostic mistake is attempting to adjust Node.js paths when troubleshooting a Native Install.

• If you used Native Install, Node.js paths and npm prefix -g are irrelevant. You must verify and add ~/.local/bin (on Unix-like systems) or %USERPROFILE%\.local\bin (on Windows) to your PATH.
• If you used npm install -g, the directory for globally installed executables is determined by npm prefix -g:
  • On Unix-like systems (macOS, Linux, WSL), executables reside in <prefix>/bin.
  • On Windows, executables are placed directly in the root of <prefix>. Commands such as npm bin -g and npm root -g do not point to the correct executable directory.

If the binary exists on disk but the shell cannot find the command, inspect PATH and shell resolution first. If calling the binary by its full absolute path also fails, inspect the exact error output and consult the official troubleshooting docs: file permissions, platform binary compatibility, or an incomplete download may require attention. Never reinstall blindly just because of a command not found error.

First Launch and Safe Exploration

Once the command resolves properly, switch into a small test project directory and start a session:

cd /path/to/test-project
claude

On first launch, the CLI prompts you to complete standard browser-based authentication. Within an active session, running /status allows you to inspect your working directory, account identifier, and currently configured model.

For your initial test, run a non-destructive introductory exercise:

Объясни назначение основных файлов в проекте. Не изменяй файлы, не устанавливай зависимости и не выполняй команды в терминале.

(Translation of the test prompt: “Explain the purpose of the main files in the project. Do not modify files, do not install dependencies, and do not execute commands in the terminal.”)

The expected response is that the agent lists the main files and explains their roles without generating code diffs or modifying the filesystem. Once the task finishes, run git diff in another shell to verify that your repository remained completely unchanged.

Understand that a prompt instruction is merely natural-language guidance provided to the model, not an enforced execution mode and not an operating system sandbox. If a repository requires strict guardrails against automatic modifications, enable plan mode:

claude --permission-mode plan

In plan mode, the agent defaults to reading files and running read-only shell commands without editing source code. However, this mode is not an OS-level isolated sandbox: when automated execution is enabled, classifier-approved commands may still run (do not assume rigid system-level isolation; confirmed by documentation as of 2026-09-15).

For a complete breakdown of permission policies, refer to the permissions guide. To exit the interactive session, press Ctrl+D.

Connecting an Independent API Provider

Installing the CLI client and configuring your model provider are two independent operational steps. If you prefer using a third-party Anthropic-compatible gateway instead of default account authentication, connection parameters are configured separately after verifying that the CLI works locally.

For instance, independent API provider BetterToken provides developers with dedicated API Keys, alongside a Dashboard to monitor model requests, token consumption, and billing. Detailed instructions for exporting required environment variables and setting the API base address are available in the BetterToken Claude Code documentation. Downloading, updating, and running the local binary itself continue to rely on the standard CLI mechanisms detailed throughout this guide.