How to Install and Use Claude Code on Linux (Complete Guide)

Tested on: Ubuntu 24.04 LTS, Fedora 40, Arch Linux — Node.js 20+ — Last updated: June 2026

Claude Code is Anthropic's official CLI that brings Claude directly into your terminal. It reads your project files, writes and edits code, runs shell commands, and explains what it's doing — all without leaving your shell session. This guide covers installation on every major Linux distro, authentication, the commands you'll actually use daily, how to configure it per project with CLAUDE.md, and real workflow examples.

What Claude Code Actually Does

Unlike a chatbot you paste code into, Claude Code runs in your terminal with access to your actual filesystem. It can:

• Read any file in your project directory
• Write and edit files directly — no copy-pasting
• Run shell commands and read their output
• Search your codebase for patterns, functions, and references
• Work across multiple files in a single instruction
• Create, move, and delete files
• Run your test suite and fix failures iteratively

The key difference from GitHub Copilot or Cursor: Claude Code works in any terminal, any editor, any environment — including remote servers over SSH. If you can open a shell, you can use it.

Prerequisites

• Node.js 18 or later (node --version to check)
• npm (comes with Node.js)
• An Anthropic account at console.anthropic.com
• Internet connection (Claude Code uses Anthropic's API — there is no offline mode)

Step 1 — Install Node.js

Claude Code requires Node.js 18+. The version in most distro repositories is outdated — use nvm or the NodeSource repository instead.

Option A: nvm (recommended — works on all distros)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

# Install and use latest LTS
nvm install --lts
nvm use --lts
nvm alias default node

# Verify
node --version   # should be 20.x or higher
npm --version

Option B: NodeSource repository

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# Fedora / RHEL / AlmaLinux
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs

# Arch Linux (current version available in official repos)
sudo pacman -S nodejs npm

Step 2 — Install Claude Code

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

# Verify installation
claude --version

If you get a permission error on npm install -g, you're using a system Node.js instead of nvm. Either switch to nvm (recommended) or fix npm's global directory:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

Step 3 — Authenticate

Run claude for the first time. It opens a browser to authenticate with your Anthropic account (claude.ai or console.anthropic.com). After login, the token is stored locally at ~/.claude/.

If the browser method doesn't work (headless servers, remote sessions), use an API key directly:

# Get your key from console.anthropic.com → API Keys
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc

# Test it
claude --version
claude -p "say hello"

The API key method is the right choice for remote servers and CI environments. The browser login is more convenient for local development machines.

Step 4 — Your First Session

cd ~/my-project
claude

Claude Code opens an interactive session. It reads your project structure automatically. You talk to it in plain English:

> what does this project do?
> explain the function in utils.py line 47
> add input validation to the login endpoint
> write unit tests for the UserService class
> there's a bug where users can't log out — find it and fix it
> refactor the database connection to use a connection pool

Claude Code shows you what it plans to do before doing it. You approve or reject each action. It doesn't silently delete files or run destructive commands without showing you first.

Slash Commands

Inside a session, slash commands control Claude Code's behaviour:

CLAUDE.md — Per-Project Configuration

This is the feature most guides skip. A CLAUDE.md file in your project root gives Claude Code persistent context about your project. Every session reads it automatically — you don't have to re-explain your stack, conventions, or rules each time.

touch CLAUDE.md

A useful CLAUDE.md for a Python project:

# Project: MyApp API

## Stack
- Python 3.12, FastAPI, PostgreSQL
- SQLAlchemy 2.0 (async), Alembic for migrations
- pytest for testing, ruff for linting

## Conventions
- All endpoints return JSON with { "data": ..., "error": null } shape
- Use snake_case for variables, PascalCase for classes
- Never use print() — use the logger from app/logging.py
- All database calls must go through the repository layer in app/repos/

## Commands
- Run tests: pytest tests/ -v
- Lint: ruff check . && ruff format .
- Start dev server: uvicorn app.main:app --reload

## What not to touch
- Do not modify alembic.ini
- Do not edit files in app/generated/ — they are auto-generated

With this file in place, Claude Code knows your conventions without being told. It won't use print() instead of the logger, won't bypass the repository layer, and won't touch the generated files.

Non-Interactive Mode: One-Shot Commands

The -p flag runs a single instruction and exits — useful for scripts, CI pipelines, and repeatable tasks:

# Run a single task and exit
claude -p "add type hints to all functions in src/utils.py"

# Pipe output to a file
claude -p "generate a changelog from the git log since v1.2.0" > CHANGELOG.md

# Use in a shell script
claude -p "update the version number in pyproject.toml to $NEW_VERSION"

# Run tests and fix failures automatically
claude -p "run the test suite and fix any failing tests"

Real Workflow Examples

Debugging a production error

cd ~/myapp
claude

> I'm getting this error in production: "AttributeError: 'NoneType' object has no attribute 'user_id'" in the checkout flow. Find the cause and fix it.

Claude Code searches the codebase for the checkout flow, traces the call chain, identifies where None is returned when a user object is expected, proposes the fix, and edits the file. You review the diff and approve.

Adding tests to untested code

> write comprehensive pytest tests for the PaymentService class. Cover happy path, edge cases, and error conditions. Mock the Stripe API calls.

Refactoring across multiple files

> rename the UserProfile model to Profile everywhere in the codebase — models, views, serializers, tests, and migrations

Understanding a new codebase

> I just cloned this repo. Give me a map of the architecture: what the main components are, how they communicate, and where the entry points are.

IDE Integration

VS Code

Search for Claude Code in the VS Code Extensions panel (Ctrl+Shift+X). The extension connects to the same CLI you installed — same authentication, same CLAUDE.md context, same capabilities. You get a panel inside VS Code where you can talk to Claude Code without switching to a separate terminal window.

JetBrains IDEs

The Claude Code plugin is available for IntelliJ IDEA, PyCharm, WebStorm, GoLand, and other JetBrains products through the JetBrains Marketplace. Search for Claude Code in Settings → Plugins → Marketplace.

Terminal inside an IDE

You don't need the extension at all. Run claude in the integrated terminal inside VS Code, Neovim, Emacs, or any editor — it works the same way. The extension just adds a dedicated panel for convenience.

Permissions and Safety

Claude Code asks for confirmation before taking potentially destructive actions. There are three permission levels:

• Read files: always allowed, no confirmation needed
• Write files / run safe commands: shown to you, confirmed automatically in most cases
• Destructive operations (delete files, run risky commands): always requires explicit approval

You can always see what Claude Code is about to do before it does it. The /review command shows every file change made in the current session. Nothing is applied silently.

Tracking Usage and Cost

Claude Code is token-based. Use /cost during a session to see current spend:

> /cost
Session cost: $0.43
Input tokens: 48,231
Output tokens: 2,847

Cost depends heavily on what you're doing. Asking Claude to read and understand a large codebase uses more input tokens than asking it to write a small function. For ongoing projects, /compact periodically compresses the conversation history to reduce token usage without losing important context.

Set spend limits in console.anthropic.com → Settings → Billing to avoid surprises.

Step 5 — Keep Claude Code Updated

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

# Or check the current installed version vs latest
npm outdated -g @anthropic-ai/claude-code

Claude Code vs Alternatives

Claude Code's strength is the combination of terminal-native operation, direct file editing, and access to Claude's reasoning. If you need offline AI coding assistance, pair it with Ollama for local models — use Claude Code when connected, Ollama when offline.

Troubleshooting

claude: command not found after installation

# Find where npm installed it
npm bin -g

# Add to PATH
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc
source ~/.bashrc

Authentication loop — browser keeps opening

Switch to the API key method. Get your key from console.anthropic.com and set ANTHROPIC_API_KEY in your shell config as shown in Step 3.

nvm: command not found after install

source ~/.bashrc# If using zsh:source ~/.zshrc

Context window full — Claude stops responding to large tasks

> /compact
# Compresses history. Then continue the task.

Claude Code edits the wrong files

Add a CLAUDE.md to your project root explicitly listing what's off-limits. Use the "What not to touch" section shown earlier. Claude Code reads this on every session start.

Frequently Asked Questions

Is Claude Code free?

Claude Code itself is free to install. Usage costs are token-based, charged to your Anthropic account. There is a free tier with limited tokens per month. For individual developers working on real projects, expect $5–30/month depending on how heavily you use it. Check console.anthropic.com for current pricing.

Does Claude Code send my code to Anthropic?

Yes — the files Claude Code reads are sent to Anthropic's API as part of the context. Don't use it on projects with credentials, private keys, or data covered by strict confidentiality agreements unless your organisation has an enterprise agreement with data processing terms.

Does it work on remote servers?

Yes. SSH into the server, install Node.js and Claude Code there, set ANTHROPIC_API_KEY and run claude. It works identically to local — it reads files on the remote server, not your local machine.

Does Claude Code work with local models?

No. Claude Code requires Anthropic's API. For fully offline AI coding assistance, use Aider (supports Ollama) or Continue.dev with a local Ollama backend instead.

What to Do Next

Once Claude Code is running, the first thing worth doing is creating a CLAUDE.md in your main project — it immediately makes every session more useful by eliminating the need to re-explain your stack each time. Then try the one-shot mode with -p for a repeatable task like running tests and fixing failures, and check /cost after a working session to calibrate how much you're spending.

For offline AI that works without internet, install Ollama alongside Claude Code — local models for quick questions and syntax, Claude Code for the heavy reasoning work that needs it.