How to Install Claude Code: Terminal Setup, Authentication, and Troubleshooting Guide

Last updated: October 13, 2026

Claude Code runs as agentic terminal interface from Anthropic. Install requires Node.js runtime version 18 or higher, active Anthropic billing setup, and terminal access to target source repositories. Command npm install -g @anthropic-ai/claude-code installs utility globally, followed by interactive OAuth terminal login to Anthropic Console.

System Requirements and Platform Prerequisites

Claude Code operates inside local shell environments. Tool inspects files, runs build scripts, stages Git commits, and modifies codebases directly. Engine requires specific runtime parameters before npm package installation executes cleanly.

• Node.js: Node.js 18.0.0 or higher required. Node.js 20 LTS recommended. Verify active release with node -v.
• Package Manager: npm 9.0.0 or higher bundled with Node.js. Yarn and pnpm work for project dependencies, but global CLI registration uses npm.
• Operating System: macOS 10.15+, Ubuntu 20.04+/Debian 11+, or Windows 10/11 through Windows Subsystem for Linux (WSL2). Native Windows Command Prompt or PowerShell lacks required POSIX terminal primitives.
• Git: Version 2.23+ required for automated diff management, branch creation, and staging workflows.
• Anthropic Account: Console account with funded API credits, or enterprise seat. Standalone browser subscription models differ; review our guide on how to cancel Claude Pro if moving direct developer billing to API console accounts.

Environment Compatibility Matrix

Review deployment parameters before global package installation. Table details runtime compatibility across operating systems and execution targets.

Pre-Installation Configuration: Node.js and Permissions

Global npm packages often trigger permission errors when installed using system-level package managers. Default Linux and macOS directories under /usr/local/lib/node_modules require root ownership. Running global installations under sudo creates broken permission states for downstream CLI file writes.

Resolve directory ownership before installation by managing Node runtimes through Node Version Manager (nvm) or configuring dedicated user npm prefix.

Configure custom npm prefix without root privileges:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
source ~/.bashrc

Confirm directory write access. Verify path points to user home directory:

npm config get prefix

Discover other development utilities and platform guides inside our AI Tools directory.

Step-by-Step Installation Sequence

Follow this exact sequence to deploy Claude Code on supported Unix environments and WSL2 platforms.

1. Open your terminal application (Terminal on macOS, standard shell on Linux, or WSL terminal on Windows).
2. Verify active Node.js runtime version:node --versionIf returned value sits below v18.0.0, update Node.js via your environment manager before proceeding.
3. Run the global package installation command:npm install -g @anthropic-ai/claude-code
4. Confirm binary placed correctly within execution path:claude --versionSystem must return installed version number without throwing command-not-found errors.
5. Navigate to directory containing software project:cd /path/to/target-repository
6. Initialize Claude Code CLI inside project folder:claude
7. Authenticate utility when browser redirect prompt appears. Tool generates unique OAuth handshake linking terminal session to Anthropic Console credentials.
8. Approve requested workspace file-system permissions inside shell prompt.

Authentication Routing and API Key Management

Claude Code consumes Anthropic platform tokens directly. Process uses one of two authentication methods: interactive OAuth console handshake or static environment variable injection.

Interactive browser flow represents default path. Executing claude without predefined tokens opens OAuth URL. Logging into Anthropic Console creates locally stored session key inside ~/.claude/config.json.

For headless remote development boxes, SSH sessions, or automated CI/CD runners, bypass interactive login by declaring explicit API key:

export ANTHROPIC_API_KEY="sk-ant-api03-..."
claude

Keep API keys restricted. Adding variable to ~/.bashrc or ~/.zshrc automates persistence across terminal restarts. Confirm token balances inside Anthropic developer console; exhausted credit limits cause CLI model call timeouts. For broader AI tooling cost planning, developers switching models often review how to upgrade to ChatGPT Plus alongside Anthropic usage.

Security and Filesystem Execution Boundaries

Claude Code functions as an autonomous terminal agent. Tool reads file trees, rewrites files, and directly spawns terminal subprocesses using user credentials.

Do not execute Claude Code with elevated administrative access (such as root or sudo). The utility inherits full filesystem permissions of calling shell user. Run commands exclusively inside version-controlled repositories where uncommitted changes can be discarded via Git. Restrict execution on systems holding exposed production credentials or unencrypted sensitive environment files.

By default, Claude Code requests manual confirmation before running bash scripts or editing file paths outside working directory. Never disable interactive prompt checks when working on critical host systems.

Common Installation Errors and Diagnostics

Diagnostic table below maps frequent runtime failures to explicit remediation commands.

Post-Installation Verification Checklist

Perform these confirmation checks inside terminal to ensure complete operational readiness:

• Binary responds to global version probe: claude --version outputs semantic release string.
• Git repository cleanly recognized: Tool identifies local branch status when run inside project root.
• Authentication handshake intact: claude doctor or simple diagnostic prompt verifies model connectivity without authentication re-prompts.
• Workspace read access verified: CLI successfully generates repo map without file read permission faults.
• Bash subprocess functional: Test command run within agent loop successfully outputs exit code 0.

Frequently Asked Questions

Does Claude Code work on native Windows without WSL?

No. Claude Code requires POSIX terminal mechanics, child process controls, and standard Unix shell integration. Windows installations require WSL2 running modern Linux distribution like Ubuntu. Running npm package directly in Windows Command Prompt or PowerShell leads to runtime exceptions during process orchestration.

Can I run Claude Code using a standard Claude Pro web subscription?

Claude Code uses Anthropic API billing infrastructure, distinct from standard web chat subscriptions. Authentication links to Anthropic Console account requiring pay-as-you-go API credits. Direct consumer Claude Pro web subscriptions do not provide generic API tokens consumed by command-line tooling.

How do I update Claude Code to the latest release?

Update utility by re-running global npm install command: npm install -g @anthropic-ai/claude-code@latest. Verify update by checking claude --version against upstream npm registry release tags.

Add PCGearWiki as a preferred source on Google