Claude Code on Linux: Ubuntu, Debian, Fedora, Arch Installation Guide (2026)

System Requirements

Before installing, confirm your system meets these requirements:

• Distribution: Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+, Fedora (current), RHEL 8+, or any glibc-based distribution
• RAM: 4 GB minimum. 8 GB or more recommended for large codebases
• Shell: Bash or Zsh. The installer adds the binary to your PATH automatically
• Network: Active internet connection. Claude Code communicates with Anthropic's API
• Account: Claude Pro ($20/month), Max ($100-200/month), Teams, Enterprise, or Anthropic Console with API credits

The free Claude.ai plan does not include Claude Code access. You need a paid subscription or Console credits.

Ubuntu and Debian

The native installer works on Ubuntu 20.04, 22.04, 24.04 and Debian 10, 11, 12 without any prerequisites. Run this from your terminal:

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

The installer downloads the Claude Code binary, places it at ~/.local/bin/claude, and adds that directory to your PATH if it is not already there. It also stores versioned binaries at ~/.local/share/claude/versions/ for rollback support.

Verify the installation

# Check version
claude --version

# Run the built-in diagnostic
claude doctor

# Navigate to a project and start
cd ~/your-project
claude

PATH fix (if needed)

If the installer completes but claude is not found, your shell's PATH does not include ~/.local/bin. Fix it:

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

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

Fedora and RHEL

Claude Code is not in Fedora's official repositories. The native installer handles everything:

# Optional: update your system first
sudo dnf upgrade --refresh

# Install Claude Code
curl -fsSL https://claude.ai/install.sh | bash

Verify and fix PATH the same way as Ubuntu above. On Fedora, ~/.local/bin is often already in PATH for interactive shells, but not for login shells used by SSH connections or cron. Add it explicitly if you plan to use Claude Code in those contexts.

which -a claude
# Expected: /home/username/.local/bin/claude

claude --version

Arch Linux

Two options on Arch: the native installer (same curl command), or the AUR package for users who prefer pacman-style management.

Option 1: Native installer

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

Option 2: AUR

# Latest version
yay -S claude-code

# Stable channel (approximately one week behind latest)
yay -S claude-code-stable

The AUR packages do not auto-update. Run yay -Syu claude-code periodically to get new versions. The native installer auto-updates in the background by default.

Alpine Linux

Alpine uses musl libc instead of glibc. The native installer's bundled ripgrep binary is compiled for glibc and will not run on Alpine without additional packages. Install these first:

apk add libgcc libstdc++ ripgrep

Then tell Claude Code to use the system ripgrep instead of the bundled one. Add this to your ~/.claude/settings.json:

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

Now run the standard installer:

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

Alpine is common in Docker images. This same setup works inside Alpine-based containers for CI/CD pipelines.

npm Installation (Deprecated)

The npm method still works but Anthropic officially deprecated it in favor of the native installer. If you are on this path, switch now:

# Install the native binary
curl -fsSL https://claude.ai/install.sh | bash

# Remove the old npm installation
npm uninstall -g @anthropic-ai/claude-code

If you need to keep using npm for compatibility (for example, in a monorepo where Claude Code is a dev dependency), install Node.js 18+ first. Use nvm to avoid permission issues:

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

# Install Node.js 22 LTS (recommended)
nvm install 22
nvm use 22

# Configure user-level npm prefix (avoids sudo)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Install Claude Code
npm install -g @anthropic-ai/claude-code

API Key and Authentication

On first run, Claude Code opens your browser for OAuth authentication with your Anthropic account. The session token is stored at ~/.claude.json.

For API key authentication (required for headless servers, CI/CD, and automated agents), set the ANTHROPIC_API_KEY environment variable:

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

Reload your shell or source the file:

source ~/.bashrc   # or source ~/.zshrc

Verify Claude Code can authenticate:

claude doctor

SSH and Headless Server Setup

Claude Code works on headless Linux servers without a display or desktop environment. The setup has two parts: getting Claude Code installed and authenticated, then keeping sessions alive across SSH disconnections.

Authentication on a headless server

When you run claude on a server without a browser, it prints a URL instead of opening one automatically. Copy that URL, open it on your local machine, and complete the OAuth flow. The token is saved on the server side.

# SSH into your server
ssh user@your-server.com

# Run claude - it will print an auth URL
claude
# Output: Visit https://claude.ai/oauth/... to authenticate
# Open that URL in your local browser, complete login
# Press Enter on the server after completing auth

For automated environments where browser auth is not possible, use an API key from the Anthropic Console instead:

# Add to your server's ~/.bashrc
export ANTHROPIC_API_KEY=sk-ant-api03-...

# Test non-interactive mode
claude -p "list the files in this directory" --output-format json

Non-interactive (print) mode

The -p flag runs Claude Code non-interactively, prints the response to stdout, and exits. This is what you use in scripts, cron jobs, and CI pipelines:

# Single prompt, exits after response
claude -p "summarize the changes in the last 5 git commits"

# With output format for parsing
claude -p "review this file for bugs" --output-format json

# Limit turns to prevent runaway agents
CLAUDE_CODE_MAX_TURNS=5 claude -p "refactor the auth module"

tmux Integration

tmux is the standard way to keep Claude Code sessions alive on Linux servers. When you detach from a tmux session, Claude Code keeps running. Reconnect from any SSH session and pick up exactly where you left off.

Install tmux

# Ubuntu / Debian
sudo apt-get install -y tmux

# Fedora / RHEL
sudo dnf install -y tmux

# Arch
sudo pacman -S tmux

# Alpine
apk add tmux

Basic tmux workflow with Claude Code

# Start a named tmux session
tmux new-session -s claude

# Inside the session: navigate to your project and start Claude Code
cd ~/your-project
claude

# Detach without stopping Claude Code (Ctrl+b, then d)
# Ctrl+b d

# Later: reattach from any SSH session
tmux attach-session -t claude

# List active sessions
tmux list-sessions

Recommended tmux config for Claude Code

# Enable mouse support
set -g mouse on

# 256-color terminal (Claude Code renders colors correctly)
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color:Tc"

# Increase scrollback buffer for long Claude Code responses
set -g history-limit 50000

# Prevent session name truncation
set -g status-left-length 40

Reload the config after saving: tmux source-file ~/.tmux.conf

systemd Service for Background Agents

For Claude Code agents that need to run continuously as daemons, a systemd user service is cleaner than a tmux session. The agent starts on login, restarts on failure, and writes logs to journald.

Create the service file

[Unit]
Description=Claude Code Background Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/your-project
Environment=ANTHROPIC_API_KEY=sk-ant-api03-...
ExecStart=%h/.local/bin/claude -p "watch for new files and summarize changes" --output-format stream-json
Restart=on-failure
RestartSec=30
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

Enable and start the service

# Create the directory if it doesn't exist
mkdir -p ~/.config/systemd/user

# Reload systemd to pick up the new file
systemctl --user daemon-reload

# Enable on login + start now
systemctl --user enable --now claude-agent

# Check status
systemctl --user status claude-agent

# View logs
journalctl --user -u claude-agent -f

# Stop / restart
systemctl --user stop claude-agent
systemctl --user restart claude-agent

For the service to survive after you log out (not just after login), enable lingering for your user:

sudo loginctl enable-linger $USER

Linux vs macOS vs Windows

Claude Code's behavior across platforms depends on how close you are to a native Unix environment.

Common Linux Issues

claude: command not found

The installer placed the binary at ~/.local/bin/claude but that directory is not in your PATH. Open a new terminal (some distributions load ~/.local/bin automatically in new sessions) or add it manually:

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

# Verify
which claude

Permission denied during installation

This happens when ~/.local/bin/ or ~/.local/share/ is owned by root (from a previous sudo install attempt). Fix the ownership:

sudo chown -R $USER:$USER ~/.local/bin ~/.local/share/claude
# Then re-run the installer
curl -fsSL https://claude.ai/install.sh | bash

ripgrep errors on Alpine or musl systems

If you see errors about ripgrep failing to execute on Alpine or other musl-based distributions, install the system packages and disable the built-in ripgrep:

apk add libgcc libstdc++ ripgrep

# Create settings.json if it doesn't exist
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}
EOF

Authentication URL not printing on headless server

Some terminal emulators suppress URLs. Run Claude Code with the print flag to confirm the API key path works instead:

ANTHROPIC_API_KEY=sk-ant-... claude -p "say hello"

Update stuck or failing

If auto-updates fail, run a manual update:

claude update

# Or reinstall from scratch
curl -fsSL https://claude.ai/install.sh | bash

Uninstall Claude Code on Linux

# Remove the binary and version files
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

# Remove settings and session data (optional - this deletes all config)
rm -rf ~/.claude
rm -f ~/.claude.json

Frequently Asked Questions

How do I install Claude Code on Linux?

Run curl -fsSL https://claude.ai/install.sh | bash. Works on Ubuntu 20.04+, Debian 10+, Fedora, RHEL, and most glibc-based distributions. No Node.js required.

Does Claude Code work on headless Linux servers?

Yes. SSH into your server and run claude. It prints an authentication URL that you open on your local machine. After authenticating, the token is stored on the server. Use claude -p with an ANTHROPIC_API_KEY for fully non-interactive operation.

Does Claude Code support Alpine Linux?

Yes, with two extra steps. Install libgcc, libstdc++, and ripgrep via apk, then set USE_BUILTIN_RIPGREP=0 in your settings.json. Then run the standard installer.

Do I need Node.js to install Claude Code on Linux?

No. The native installer is self-contained. Node.js 18+ is only needed if you use the deprecated npm method.

How do I use Claude Code non-interactively in a script?

Use the -p flag: claude -p "your prompt". Set ANTHROPIC_API_KEY for authentication. Add --output-format json for parseable output in scripts. Set CLAUDE_CODE_MAX_TURNS to limit agent execution.

Is there a Claude Code desktop app for Linux?

No. The desktop app is macOS and Windows only. The CLI has no such limitation and is the primary interface for Linux users. The VS Code extension also works on Linux through the terminal.

Related Guides