Claude Code for Linux

Native Linux installation with distribution-specific guides. Supports Ubuntu, Debian, Fedora, Arch, openSUSE, and more.

Native Support

Choose Your Linux Distribution

Select your Linux distribution for tailored installation instructions.

Ubuntu

20.04 LTS+

Debian

11+

Fedora

35+

Arch

Rolling

Very Quick Installation

For experienced users - get Claude Code running in 3 commands

Linux Quick Setup 
# Install Node.js (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

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

# Run Claude Code
claude

Other distros: Replace apt commands with your package manager (dnf, pacman, zypper, etc.)

Beginner Path

Step-by-Step Guide

New to Linux package management? Follow our detailed guide with explanations for each command.

  • Package manager basics
  • Node.js installation explained
  • Terminal tips and tricks
  • Permission management
Start Beginner Guide

Professional Path

Advanced Setup

Experienced Linux user? Jump to advanced configurations, containerization, and enterprise features.

  • One-command installation
  • Docker and containerization
  • Server deployment
  • Advanced MCP configurations
Advanced Setup

System Requirements

Claude Code runs natively on most modern Linux distributions.

Kernel Version Linux 4.15+ (most distributions from 2018+)
Architecture x86_64 (AMD64) or ARM64 (aarch64)
Memory 2GB RAM minimum (4GB+ recommended)
Storage 1GB free space for Node.js and Claude Code
Network Internet connection for installation and API access
Permissions sudo access for package installation

Supported Distributions

  • Ubuntu 20.04 LTS and newer
  • Debian 11 (Bullseye) and newer
  • Fedora 35 and newer
  • CentOS Stream 8+, RHEL 8+
  • Arch Linux (rolling release)
  • openSUSE Leap 15.3+, Tumbleweed
  • Linux Mint 20+
  • Pop!_OS 20.04+

Package Managers

  • apt - Ubuntu, Debian, derivatives
  • dnf/yum - Fedora, RHEL, CentOS
  • pacman - Arch Linux, Manjaro
  • zypper - openSUSE
  • snap - Universal packages
  • flatpak - Universal packages

Beginner Installation Guide

Follow these detailed steps to install Claude Code on Linux. Perfect for users new to Linux package management.

1 Update Your System

5-10 minutes

First, update your system packages to ensure you have the latest security updates and package information.

Ubuntu/Debian (apt)

# Update package list
sudo apt update

# Upgrade installed packages
sudo apt upgrade -y

# Install essential tools
sudo apt install curl wget gnupg2 software-properties-common -y

Fedora (dnf)

# Update system packages
sudo dnf update -y

# Install essential tools
sudo dnf install curl wget gnupg2 -y

Arch Linux (pacman)

# Update system
sudo pacman -Syu

# Install essential tools
sudo pacman -S curl wget gnupg base-devel

openSUSE (zypper)

# Update system
sudo zypper update -y

# Install essential tools
sudo zypper install curl wget gpg2

Why update first? This ensures you have the latest package information and security updates before installing new software.

2 Install Node.js

5 minutes

Claude Code requires Node.js 18 or higher. We'll install the latest LTS version using the NodeSource repository.

Method 1: NodeSource Repository (Recommended)

This method provides the latest Node.js versions for Ubuntu/Debian:

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Method 2: Distribution Packages

Fedora
# Install Node.js from Fedora repos
sudo dnf install nodejs npm -y
Arch Linux
# Install Node.js from Arch repos
sudo pacman -S nodejs npm

Method 3: Node Version Manager (NVM)

For managing multiple Node.js versions:

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell
source ~/.bashrc

# Install latest LTS Node.js
nvm install --lts
nvm use --lts

Configure npm for Global Packages

# Create directory for global packages
mkdir -p ~/.npm-global

# Configure npm to use this directory
npm config set prefix ~/.npm-global

# Add to PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Verification: You should see Node.js v18+ and npm v8+ when running the version commands.

3 Install Claude Code

2 minutes

Now we can install Claude Code using npm. This downloads the latest version from the official repository.

Install Claude Code Globally

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

# Verify installation
claude --version

# Check if it's in PATH
which claude

Alternative: Using Snap (Universal)

If available on your distribution:

# Install via Snap (if available)
sudo snap install node --classic
sudo snap install claude-code

Troubleshooting Installation

If you encounter permission issues:

# Fix npm permissions (if needed)
sudo chown -R $(whoami) ~/.npm-global

# Or reinstall with correct permissions
npm config set prefix ~/.npm-global
npm install -g @anthropic-ai/claude-code

Important: Never use sudo npm install -g as this can cause permission and security issues.

4 Set Up Authentication

3 minutes

Configure Claude Code to work with your Anthropic account using either Claude Max or an API key.

Option A: Claude Max (Recommended)

Best for regular users ($20/month):

  1. Navigate to a project directory
  2. Run claude
  3. Follow OAuth prompts in browser
  4. Complete authentication
# Navigate to your project
cd ~/Projects/your-project

# Start Claude Code
claude

Option B: API Key

For pay-per-use or enterprise:

  1. Get API key from Anthropic Console
  2. Set environment variable
  3. Add to shell profile
# Set API key
export ANTHROPIC_API_KEY=your_key_here

# Add to shell profile
echo 'export ANTHROPIC_API_KEY=your_key' >> ~/.bashrc
source ~/.bashrc

Shell-Specific Configuration

Shell Config File Command
Bash ~/.bashrc echo 'export ANTHROPIC_API_KEY=key' >> ~/.bashrc
Zsh ~/.zshrc echo 'export ANTHROPIC_API_KEY=key' >> ~/.zshrc
Fish ~/.config/fish/config.fish set -Ux ANTHROPIC_API_KEY key

Tip: Check your default shell with echo $SHELL to know which config file to use.

5 First Use and Testing

5 minutes

Test Claude Code with your first project and learn the basic Linux workflow.

Create a Test Project

# Create a new project directory
mkdir ~/claude-test
cd ~/claude-test

# Create a simple Python script
cat > hello.py << 'EOF'
#!/usr/bin/env python3
print("Hello Claude from Linux!")
EOF

# Make it executable
chmod +x hello.py

# Create a README
echo "# My First Claude Code Project on Linux" > README.md

Start Claude Code

# Start Claude Code in your project
claude

# Try some basic commands
> "Explain what this Python script does"
> "/init"  # Generate project documentation
> "/help"  # See all available commands
> "/doctor" # Check system health

Linux-Specific Commands to Try

  • /permissions - Manage file permissions
  • /status - Check system status
  • /terminal-setup - Optimize terminal settings
  • /clear - Clear conversation context
  • /exit - Exit Claude Code

Success! You've successfully installed Claude Code on Linux. Welcome to AI-powered development on the world's most powerful OS!

Professional Installation Guide

Advanced setup for experienced Linux users with server deployment, containerization, and enterprise features.

One-Command Installation Scripts

2 minutes

Automated installation scripts for different Linux distributions.

Ubuntu/Debian

# Complete installation
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && \
sudo apt-get install -y nodejs && \
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

Fedora/RHEL

# Complete installation
sudo dnf install -y nodejs npm && \
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

Arch Linux

# Complete installation
sudo pacman -S nodejs npm && \
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

Universal (NVM)

# Install with NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash && \
source ~/.bashrc && \
nvm install --lts && \
nvm use --lts && \
npm install -g @anthropic-ai/claude-code

Docker Deployment

Containerized Claude Code for development, CI/CD, and production environments.

Dockerfile

# Dockerfile for Claude Code
FROM node:20-alpine

# Install system dependencies
RUN apk add --no-cache git curl bash

# Create non-root user
RUN addgroup -g 1001 -S claude && \
    adduser -S claude -u 1001 -G claude

# Set working directory
WORKDIR /workspace

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

# Switch to non-root user
USER claude

# Set environment variables
ENV ANTHROPIC_API_KEY=""
ENV NODE_OPTIONS="--max-old-space-size=4096"

# Default command
CMD ["claude"]

Docker Compose

# docker-compose.yml
version: '3.8'

services:
  claude-code:
    build: .
    volumes:
      - ./:/workspace
      - ~/.claude.json:/home/claude/.claude.json:ro
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    stdin_open: true
    tty: true
    working_dir: /workspace

Usage Examples

# Build and run interactively
docker build -t claude-code .
docker run -it --rm -v $(pwd):/workspace -e ANTHROPIC_API_KEY=your_key claude-code

# Run with Docker Compose
docker-compose run --rm claude-code

# Automated mode for CI/CD
docker run --rm -v $(pwd):/workspace -e ANTHROPIC_API_KEY=your_key claude-code \
  claude --dangerously-skip-permissions -p "run tests and fix any issues"

Server Deployment

Deploy Claude Code on Linux servers for team access and automation.

Systemd Service

Create /etc/systemd/system/claude-code.service:

[Unit]
Description=Claude Code Service
After=network.target

[Service]
Type=simple
User=claude
WorkingDirectory=/opt/claude-workspace
Environment=ANTHROPIC_API_KEY=your_key
Environment=NODE_OPTIONS=--max-old-space-size=8192
ExecStart=/usr/local/bin/claude --headless
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
# Enable and start service
sudo systemctl enable claude-code
sudo systemctl start claude-code
sudo systemctl status claude-code

Nginx Proxy

For web-based access:

# /etc/nginx/sites-available/claude-code
server {
    listen 80;
    server_name claude.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Advanced Configuration

Enterprise-grade configurations for production environments.

Global Configuration

Create /etc/claude/config.json:

{
  "defaultModel": "claude-sonnet-4",
  "permissions": {
    "allowedTools": ["Edit", "Bash(git*)"],
    "deniedTools": ["Bash(rm*)", "Bash(sudo*)"]
  },
  "preferences": {
    "autoCompact": true,
    "compactThreshold": 100000,
    "maxMemoryUsage": "8GB"
  },
  "logging": {
    "level": "info",
    "file": "/var/log/claude-code.log"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/opt/projects"]
    }
  }
}

Environment Setup

Add to /etc/environment:

# System-wide environment variables
ANTHROPIC_API_KEY=your_key
CLAUDE_MODEL=claude-sonnet-4
NODE_OPTIONS=--max-old-space-size=8192
MCP_DEBUG=false

# Performance tuning
UV_THREADPOOL_SIZE=16
NODE_ENV=production
# Security hardening
# Create dedicated user
sudo useradd -r -s /bin/bash -d /opt/claude claude
sudo mkdir -p /opt/claude/{workspace,logs}
sudo chown -R claude:claude /opt/claude

# Set up log rotation
sudo tee /etc/logrotate.d/claude-code << 'EOF'
/var/log/claude-code.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 claude claude
}
EOF

CI/CD Integration

Integrate Claude Code into your continuous integration and deployment pipelines.

GitHub Actions

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
        
    - name: Install Claude Code
      run: npm install -g @anthropic-ai/claude-code
      
    - name: Review PR
      run: |
        claude --dangerously-skip-permissions \
          -p "Review this PR for code quality, security, and best practices"
      env:
        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

GitLab CI

# .gitlab-ci.yml
stages:
  - review
  - test

claude-review:
  stage: review
  image: node:20-alpine
  before_script:
    - apk add --no-cache git
    - npm install -g @anthropic-ai/claude-code
  script:
    - claude --dangerously-skip-permissions 
        -p "Analyze code changes and suggest improvements"
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  only:
    - merge_requests

Jenkins Pipeline

// Jenkinsfile
pipeline {
    agent any
    
    environment {
        ANTHROPIC_API_KEY = credentials('anthropic-api-key')
    }
    
    stages {
        stage('Setup') {
            steps {
                sh 'npm install -g @anthropic-ai/claude-code'
            }
        }
        
        stage('Code Review') {
            steps {
                sh '''
                    claude --dangerously-skip-permissions \
                      -p "Review code changes for quality and security issues"
                '''
            }
        }
        
        stage('Generate Documentation') {
            steps {
                sh 'claude -p "Update project documentation based on code changes"'
            }
        }
    }
}

Linux Troubleshooting

Solutions to common issues specific to Linux distributions and environments.

Package Manager Issues

Node.js version too old

# Ubuntu/Debian: Add NodeSource repo
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora: Enable NodeJS module
sudo dnf module enable nodejs:20
sudo dnf install nodejs npm

Permission denied errors

# Fix npm global directory permissions
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Missing build tools

# Ubuntu/Debian
sudo apt install build-essential

# Fedora
sudo dnf groupinstall "Development Tools"

# Arch
sudo pacman -S base-devel

Runtime Issues

Command not found: claude

# Check if installed
npm list -g @anthropic-ai/claude-code

# Check PATH
echo $PATH | grep npm

# Add to PATH if missing
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Memory issues

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"

# Add to shell profile
echo 'export NODE_OPTIONS="--max-old-space-size=8192"' >> ~/.bashrc

# Check system memory
free -h

Network connectivity

# Test API connectivity
curl -I https://api.anthropic.com

# Check DNS resolution
nslookup api.anthropic.com

# Test with different DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Distribution-Specific Issues

SELinux (RHEL/Fedora)

# Check SELinux status
sestatus

# Temporarily disable (if needed)
sudo setenforce 0

# Create SELinux policy for Claude Code
sudo setsebool -P httpd_can_network_connect 1

AppArmor (Ubuntu)

# Check AppArmor status
sudo aa-status

# If needed, create profile exception
sudo aa-complain /usr/bin/node

Snap package issues

# If using snap-installed Node.js
sudo snap refresh node

# Or switch to system Node.js
sudo snap remove node
# Then install via package manager

Performance Optimization

File system optimization

# Use tmpfs for temporary files
sudo mount -t tmpfs -o size=2G tmpfs /tmp

# Add to /etc/fstab for persistence
echo "tmpfs /tmp tmpfs size=2G 0 0" | sudo tee -a /etc/fstab

Process limits

# Increase file descriptor limits
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

# Check current limits
ulimit -n

CPU optimization

# Set CPU governor to performance
echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

# Check CPU info
lscpu | grep -E "Model name|CPU\(s\)|Thread"

🐧 Linux Installation Complete!

Excellent! You've successfully installed Claude Code on Linux. Here's what to explore next:

Explore Features Setup MCP View Examples

Need help? Check our troubleshooting guide or visit the community resources.

All Claude Commands