May 5, 2026·11 min read

Claude Code on Linux: Install, Configure, Optimise

Claude CodeSetupLinuxTutorial

Linux is a first-class Claude Code platform

Claude Code was built on Linux. Anthropic's own servers run Linux. The binary is tested on Linux first. If you are a Linux developer, you are using Claude Code on the platform it was designed for, and you have the most install options of any OS.

This guide covers every major Linux family: Ubuntu and Debian via apt, Fedora and RHEL via dnf, Arch Linux via the AUR or native installer, and Alpine via apk. It also covers shell configuration for bash, zsh, and fish, the CLAUDE.md setup that determines how useful Claude Code actually is, and the common issues specific to Linux environments. For the conceptual introduction to what Claude Code is, read what is Claude Code first.

System requirements: Linux with x86_64 or ARM64 architecture, 4 GB RAM minimum, and an internet connection. Supported distributions: Ubuntu 20.04+, Debian 10+, Fedora (current), Alpine 3.19+, and equivalents. The native installer also works on most other distributions.

Install method overview

There are three install paths on Linux. Choose based on your distro and preferences.

Native installer: Works on all Linux distributions. One command. Puts the binary at ~/.local/bin/claude. Auto-updates in the background. This is the recommended path for most developers.

Package manager (apt, dnf, apk): Works on Debian/Ubuntu, Fedora/RHEL, and Alpine. Installs via your system package manager. Does not auto-update through Claude Code itself but updates arrive through your normal apt upgrade or dnf upgrade workflow. The right choice if you want all software managed through a single package manager.

npm: Works everywhere Node.js 18+ is installed. Useful for pinning a version or keeping Claude Code in a Node.js-centric toolchain.

Ubuntu and Debian

Native installer (recommended)

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

Restart your terminal, then verify:

claude --version

The binary lands at ~/.local/bin/claude. The installer adds the PATH configuration to your shell rc file automatically. If claude is not found after restarting, see the shell configuration section below.

apt package manager

Anthropic publishes a signed apt repository. This is the right choice if you want Claude Code to fit into your apt upgrade workflow.

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Before trusting the key, verify the GPG fingerprint:

gpg --show-keys /etc/apt/keyrings/claude-code.asc

The fingerprint should read 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE. If it does not match, do not proceed.

To update later:

sudo apt update && sudo apt upgrade claude-code

To use the rolling channel instead of stable, change both stable occurrences in the repository URL to latest.

Fedora and RHEL

dnf package manager

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

dnf downloads the GPG key on first install and prompts you to confirm the fingerprint. Verify it matches 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE before accepting.

To update later:

sudo dnf upgrade claude-code

Native installer on Fedora

The native installer also works on Fedora without the repo setup:

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

The tradeoff: you get auto-updates but the binary is outside dnf's tracking. If you want everything in dnf, use the repo path above. If auto-updates matter more than package manager hygiene, use the native installer.

Arch Linux

Arch does not have an official Anthropic repository, but the native installer works cleanly on Arch:

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

The binary installs to ~/.local/bin/claude, which respects XDG Base Directory conventions. If you are on a standard Arch install, ~/.local/bin is likely already in your PATH from /etc/profile or your shell rc. Verify:

echo $PATH | tr ':' '\n' | grep local

If ~/.local/bin is not listed, add it in your ~/.bashrc or ~/.zshrc (see the shell configuration section below).

Community-maintained AUR packages also exist (search for claude-code on aur.archlinux.org). AUR packages are not maintained by Anthropic, so check maintainer reputation and PKGBUILD content before using them. The native installer is safer and always up to date.

Alpine Linux

Alpine requires a few dependencies before the native installer works, because Alpine uses musl libc rather than glibc:

apk add libgcc libstdc++ ripgrep

Then install Claude Code:

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

After install, disable the bundled ripgrep in favour of the system one. Add this to your shell rc file:

export USE_BUILTIN_RIPGREP=0

Or set it in ~/.claude/settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Alpine's apk repository is also available for package-manager installs:

wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

Verify the key: sha256sum /etc/apk/keys/claude-code.rsa.pub should print 395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6.

Shell configuration on Linux

Linux distributions ship with different default shells. The most common:

Ubuntu 22.04+: bash (default), but many developers switch to zsh
Fedora 39+: bash
Arch: bash (default), zsh, fish widely used
Alpine: ash (busybox), or bash if installed

Check yours:

echo $SHELL

bash

The native installer adds a PATH export to ~/.bashrc automatically. If it did not, or if you need to add it manually:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

If you use ~/.bash_profile instead of (or alongside) ~/.bashrc (common on some distributions where .bash_profile is the login shell config), add the same line there.

zsh

If you have switched to zsh (common on Arch and for macOS-crossover developers), the PATH export goes in ~/.zshrc:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If you use Oh My Zsh or Zinit, add the export before the framework initialisation line so it is available to all plugins.

fish

Fish shell uses its own path management syntax. Add ~/.local/bin once:

fish_add_path $HOME/.local/bin

fish_add_path writes a universal variable, so this persists across shells and sessions without needing to edit config.fish. Run claude --version after to confirm it is found.

Verifying the install from any shell

After configuration:

claude --version
claude doctor

claude doctor runs a health check on authentication status, PATH configuration, and MCP server availability. If something is misconfigured, it tells you what and gives you the fix.

Authentication

Run Claude Code from your project directory:

cd ~/projects/your-project
claude

Claude Code opens a browser-based authentication URL. On a Linux desktop (GNOME, KDE, or others with a browser installed), it opens automatically. On a headless server or in a remote session, it prints the URL for you to open manually:

To authenticate, open this URL in your browser:
https://claude.ai/oauth/device?code=...

Copy the URL to any browser. Log in with your Anthropic account. The token is stored locally at ~/.claude.json and persists across sessions.

Required account tier: Pro, Max, Teams, or Enterprise. The free Claude.ai plan does not include Claude Code access.

Authentication on headless servers

On a server without a browser (a VPS, a CI runner, or an SSH session), authentication works via API keys rather than OAuth. If you have an Anthropic API key:

export ANTHROPIC_API_KEY=sk-ant-...
claude

Set this permanently in your shell rc file or in your project's environment management so you do not have to export it every session.

The CLAUDE.md file on Linux

CLAUDE.md is the project-specific configuration file Claude Code reads at the start of every session. It is the highest-leverage configuration step after install. Without it, Claude Code uses generic defaults. With it, output fits your project's conventions from the first message.

A CLAUDE.md for a typical Linux backend project:

# Project rules

## Environment
- Linux (Ubuntu 24.04), x86_64
- Node: 22 (via nvm)
- Package manager: npm
- Run: `npm run dev`
- Build: `npm run build`

## Database
- PostgreSQL 16, local instance at localhost:5432
- Migrations: `npm run migrate` (uses db-migrate)
- Never modify migration files after they have been applied

## Testing
- Jest, run with `npm test`
- Integration tests require a running Postgres instance
- Test database: `TEST_DATABASE_URL` from .env.test

## Code conventions
- ESLint + Prettier (config in .eslintrc and .prettierrc)
- TypeScript strict mode
- Absolute imports from src/ root

## Deployment
- Docker: `docker compose up --build`
- Production: Railway (auto-deploys from main)
- Never deploy from a branch with failing tests

## Hard rules
- Environment variables in .env.local (gitignored)
- No `console.log` in production code, use the logger at src/lib/logger.ts
- Database queries go through the ORM in src/db/, never raw SQL in route handlers

Write this file once, update it when your stack changes, and Claude Code reads it every session. The result is code that uses your package manager, your test runner, your conventions, without you having to explain them every time.

Read CLAUDE.md explained for a full breakdown of what you can configure and how it affects Claude Code's behaviour across different programming languages.

Linux-specific issues and fixes

"command not found: claude" after install. The most common cause: ~/.local/bin is not in your PATH, or your shell rc was not reloaded. Fix:

source ~/.bashrc   # or ~/.zshrc depending on your shell
which claude       # should print ~/.local/bin/claude

If which claude returns nothing, the binary may not be at ~/.local/bin/claude. Check: ls -la ~/.local/bin/. If it is there but still not found, add the PATH export manually (see shell configuration above).

Permission errors during curl install. Do not run the install script with sudo. The native installer puts Claude Code in your home directory by design. Running with sudo installs to root's home directory and then claude is not found for your user. If you ran it with sudo, remove the misplaced binary and re-run without:

sudo rm -f /root/.local/bin/claude
curl -fsSL https://claude.ai/install.sh | bash

Claude Code crashes on Arch with musl. If you are on an Arch setup with musl instead of glibc (unusual but possible), the glibc-linked binary will not run. The Alpine install path (with libgcc and libstdc++ from your musl-compatible packages) is the workaround.

Auth URL not opening on headless server. Expected behaviour. Copy the printed URL and open it in a browser on any device. The auth token is tied to your Anthropic account, not the device.

File permission errors when Claude Code tries to edit. Claude Code edits files as your user. If your project was cloned as root or has root ownership, fix the permissions: sudo chown -R $USER:$USER ~/projects/your-project.

inotify watch limit exceeded. On projects with many files (monorepos, large node_modules), Linux's inotify limit can be hit. Fix:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

This is the same fix used for VS Code, Webpack, and other file-watching tools on Linux.

Update management on Linux

If you installed via the native installer, Claude Code auto-updates in the background. No action needed.

If you installed via apt, dnf, or apk, update through your package manager:

# Ubuntu/Debian
sudo apt update && sudo apt upgrade claude-code

# Fedora/RHEL
sudo dnf upgrade claude-code

# Alpine
apk update && apk upgrade claude-code

To stay on the stable channel (updates roughly one week delayed, skips regressions), add autoUpdatesChannel to your settings.json:

{
  "autoUpdatesChannel": "stable"
}

Settings.json on Linux lives at ~/.claude/settings.json. Create it if it does not exist.

Containers and remote development

Linux developers frequently work in containers or over SSH. Both patterns work with Claude Code.

Docker containers. Claude Code can be installed inside a container image. Add to your Dockerfile:

RUN curl -fsSL https://claude.ai/install.sh | bash
ENV PATH="/root/.local/bin:${PATH}"

Authentication in a container requires either an API key (ANTHROPIC_API_KEY environment variable) or a mounted ~/.claude.json credential file. OAuth browser auth is not practical inside a container.

Remote SSH development. SSH into your Linux server, install Claude Code on the server (not your local machine), and run it there. Claude Code operates on the files on the server directly, which is faster than mounting a remote filesystem locally. Authentication works via the printed URL method (copy URL, open in local browser).

VS Code Remote SSH or Dev Containers. If you use VS Code Remote, run Claude Code in the VS Code integrated terminal. It connects to the remote host or container, and Claude Code edits files directly. The setup is identical to a local install.

Building a productive workflow

The install gets Claude Code running. The configuration determines how productive it actually is. Two resources that matter immediately after install:

Claude Code memory systems covers how to build persistent project memory so Claude Code retains context about your codebase across sessions. Without this, you explain your architecture every session. With it, Claude Code already knows.

Claude Code skills explained covers how to build reusable skill files that teach Claude Code your project-specific patterns, testing conventions, and deployment procedures. Skills compound over time.

The underlying principle is the same as for any Claude Code best practices guide: Claude Code's output quality scales with the information you give it about your project. The install is two commands. The configuration is an ongoing investment that pays out with every session.

Claudify ships a pre-built Claude Code operating system (memory architecture, skill libraries, audit hooks) that works across Ubuntu, Fedora, Arch, and Alpine without modification. Run npx create-claudify from your project directory to inherit the full setup.

Quick reference

Task	Command
Install (native, all distros)	`curl -fsSL https://claude.ai/install.sh \| bash`
Install (Ubuntu/Debian apt)	See apt section above
Install (Fedora/RHEL dnf)	See dnf section above
Install (Alpine apk)	See Alpine section above
Verify install	`claude --version`
Diagnose issues	`claude doctor`
Update (native, auto)	Automatic
Update (apt)	`sudo apt update && sudo apt upgrade claude-code`
Update (dnf)	`sudo dnf upgrade claude-code`
Update (apk)	`apk update && apk upgrade claude-code`
Set API key auth	`export ANTHROPIC_API_KEY=sk-ant-...`
Shell config (bash)	`~/.bashrc`
Shell config (zsh)	`~/.zshrc`
User settings file	`~/.claude/settings.json`
Uninstall (native)	`rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude`
Uninstall (apt)	`sudo apt remove claude-code`
Uninstall (dnf)	`sudo dnf remove claude-code`