How to Install Claude Code on Ubuntu (26.04, 24.04, 22.04)

Claude Code is an agentic coding tool from Anthropic that lives in your terminal, understands your codebase, and helps you code faster through natural language commands. Unlike web-based AI assistants, Claude Code operates directly in your development environment with full context of your project files, dependencies, and git history.

Common use cases include explaining unfamiliar codebases, implementing new features from natural language descriptions, refactoring existing code, debugging errors with full stack traces, managing git workflows including commits and pull requests, and running automated code reviews. By the end of this guide, you will have Claude Code installed on Ubuntu, authenticated with your Anthropic account, and ready to use in your projects.

Choose Your Claude Code Installation Method

Ubuntu supports three installation paths for Claude Code. The native installer downloads a pre-built binary directly from Anthropic with automatic updates enabled by default. Homebrew provides an alternative package manager approach but requires manual updates. The npm method is deprecated but still functional for users who prefer Node.js-based package management.

Method	Channel	Version	Updates	Best For
Native Installer	Anthropic Official	Latest	Automatic background updates	Most users, production workflows
Homebrew	Homebrew Cask	Latest	Manual via brew upgrade	Users who manage tools through Homebrew
npm	npm Registry	Latest	Manual via npm update	Node.js developers (deprecated method)

The native installer suits most users because it provides automatic updates, works independently of Node.js, and receives direct support from Anthropic. The native binary installs to your home directory and requires no root privileges for updates.

These steps cover Ubuntu 26.04 LTS, 24.04 LTS, and 22.04 LTS. Claude Code requires a Claude Pro, Max, or Teams subscription, or an Anthropic Console account with active billing. Commands shown work identically across all supported Ubuntu LTS releases.

System Requirements

Before installing Claude Code, verify your system meets these requirements:

• Operating System: Ubuntu 20.04 or newer (26.04, 24.04, 22.04 LTS recommended)
• RAM: 4 GB minimum
• Internet: Active connection required for authentication and AI interactions
• Shell: Bash or Zsh (best supported)
• Subscription: Claude Pro ($20/month), Max ($100-200/month), Teams, or Anthropic Console with billing

The native installer includes ripgrep for code search. If search features malfunction after installation, install ripgrep separately with sudo apt install ripgrep.

Method 1: Install Claude Code via Native Installer

The native installer downloads a pre-built binary directly from Anthropic and configures automatic updates. This method works independently of Node.js and provides the most streamlined experience.

Install Required Dependencies

The installer requires curl to download the installation script:

sudo apt install curl -y

Most Ubuntu installations include curl by default, but minimal images or containers may omit it.

Run the Installation Script

Download and execute the official installer:

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

The script downloads the Claude Code binary and installs it to ~/.local/bin/claude. You should see confirmation output:

Setting up Claude Code...

✔ Claude Code successfully installed!

  Version: 2.x.x

  Location: ~/.local/bin/claude

  Next: Run claude --help to get started

The installer automatically adds ~/.local/bin to your PATH if needed. If claude returns “command not found” after installation, open a new terminal or run source ~/.bashrc to reload your shell configuration.

Install Specific Versions (Optional)

The default installation fetches the latest release. To install a specific version or the stable channel:

# Install stable channel (approximately one week behind latest)
curl -fsSL https://claude.ai/install.sh | bash -s stable

# Install specific version (replace with your target version)
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.0

The stable channel skips releases with major regressions, making it suitable for production environments where stability matters more than new features.

Verify Installation

Confirm Claude Code installed correctly:

claude --version

Expected output showing the installed version:

2.x.x (Claude Code)

Run the diagnostic command to verify all components are working correctly:

claude doctor

The doctor command checks your installation type, current version, available updates, and system configuration. A healthy installation shows output similar to:

Claude Code Doctor

Installation
  Install method: native
  Version: 2.x.x
  Update channel: latest

System
  Operating system: linux
  Node.js: Not required (native installation)
  Shell: /bin/bash

Status: All checks passed

Method 2: Install Claude Code via Homebrew

Homebrew provides an alternative installation path for users who already manage their development tools through Homebrew on Linux. This method does not auto-update; you must run upgrade commands manually.

Install Homebrew (If Not Present)

If Homebrew is not installed on your system, add it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation completes, add Homebrew to your PATH by running the commands shown in the installer output. For most users on Ubuntu, this means adding the following to your ~/.bashrc:

echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
source ~/.bashrc

Install Claude Code

Install Claude Code using the Homebrew cask:

brew install --cask claude-code

Verify Installation

Confirm the installation completed successfully:

claude --version

2.x.x (Claude Code)

Unlike the native installer, Homebrew installations do not auto-update. Run brew upgrade claude-code periodically to receive new versions. Homebrew tracks the same releases as the native installer’s “latest” channel.

Method 3: Install Claude Code via npm (Deprecated)

The npm installation method is deprecated but still functional. Anthropic recommends migrating to the native installer for better update handling and fewer dependency requirements.

This method requires Node.js 18 or higher. If you currently use npm installation, migrate to native by running /install-native from within Claude Code.

Install Node.js

Claude Code requires Node.js 18 or newer. Install Node.js using the NodeSource repository or your preferred method:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install nodejs -y

Verify Node.js installed correctly:

node --version

Expected output showing Node.js 22.x (or higher):

v22.x.x

Install Claude Code Globally

Install Claude Code as a global npm package:

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

Do NOT use sudo npm install -g as this creates permission issues and security risks. If you encounter permission errors, configure npm to use a directory in your home folder for global packages.

Verify Installation

Confirm the installation completed successfully:

claude --version

2.x.x (Claude Code)

Migrate to Native Installer

Since npm installation is deprecated, Anthropic recommends migrating to the native installer for automatic updates. From within a running Claude Code session, run:

/install-native

This installs the native binary alongside your npm installation. After migration, you can remove the npm package with npm uninstall -g @anthropic-ai/claude-code.

Authenticate Claude Code

Claude Code requires authentication before you can interact with the AI. The free tier of Claude does not include Claude Code access; you need a paid subscription or API credits.

Authentication Options

Claude Code supports multiple authentication methods:

• Claude Pro or Max subscription: Log in with your claude.ai account for unified billing across Claude web and Claude Code
• Anthropic Console: Connect through the developer console with API billing
• Claude for Teams or Enterprise: Centralized team billing with member management
• Cloud providers: Amazon Bedrock, Google Vertex AI, or Microsoft Foundry

First Launch Authentication

Navigate to your project directory and start Claude Code:

cd ~/your-project
claude

On first launch, Claude Code opens a browser window for OAuth authentication. Follow the prompts to:

1. Sign in with your Claude.ai or Anthropic Console account
2. Authorize Claude Code to access your account
3. Return to the terminal where authentication completes automatically

After successful authentication, Claude Code displays an interactive prompt where you can start entering commands.

Manage Authentication

Switch accounts or re-authenticate using slash commands from within Claude Code:

/login    # Switch to a different Anthropic account
/logout   # Sign out from your current account

Common Slash Commands

Claude Code uses slash commands for quick operations within the interactive session. Type the command at the Claude Code prompt, not your regular shell.

Essential Commands

Command	Purpose
/help	Display all available commands
/clear	Clear conversation history and start fresh
/compact	Compress conversation to reduce context usage
/cost	Show token usage and cost statistics
/doctor	Check installation health and updates
/exit	Exit Claude Code

Project and Session Commands

Command	Purpose
/init	Initialize project with CLAUDE.md guide file
/memory	Edit CLAUDE.md memory files for persistent context
/resume [session]	Resume a previous conversation by ID or name
/rename <name>	Rename current session for easier identification
/add-dir	Add additional working directories to context

Development Workflow Commands

Command	Purpose
/review	Request code review of current changes
/security-review	Security review of pending changes on current branch
/pr-comments	View pull request comments
/plan	Enter plan mode for complex implementations
/todos	List current TODO items

Basic Usage Examples

Claude Code responds to natural language prompts. These examples demonstrate common workflows.

Explore a Codebase

Ask Claude Code to explain unfamiliar code:

claude
> Explain how authentication works in this project
> What does the handleSubmit function in src/components/Form.tsx do?
> Find all API endpoints and describe their purposes

Implement Features

Describe what you want and Claude Code writes the implementation:

> Add a dark mode toggle to the settings page
> Create a function that validates email addresses
> Implement pagination for the user list API endpoint

Git Operations

Claude Code integrates deeply with Git on Ubuntu and can manage version control workflows through natural language commands:

> Commit these changes with a descriptive message
> Create a pull request for the current branch
> Show me what changed since yesterday

Non-Interactive Mode

Use the -p flag to run queries without entering interactive mode:

# Quick question
claude -p "explain this function"

# Process piped content
cat error.log | claude -p "analyze these errors"

# Continue previous conversation
claude -c -p "add tests for the function we just created"

Configure Claude Code

Claude Code stores configuration in JSON files at user and project levels.

Configuration Files

File	Purpose
~/.claude/settings.json	User settings (permissions, hooks, model overrides)
~/.claude.json	Global state (theme, OAuth, MCP servers, allowed tools)
.claude/settings.json	Project settings (shared with team via source control)
.claude/settings.local.json	Local project settings (not committed)

Access Settings Interface

Open the configuration interface from within Claude Code:

/config

This opens an interactive menu where you can configure auto-update channels, terminal settings, model preferences, and other options.

Configure Auto-Update Channel

Set the update channel in your settings file to control which releases you receive:

{
  "autoUpdatesChannel": "stable"
}

Available channels:

• latest (default): Receive new features immediately
• stable: Receive versions approximately one week old, skipping releases with major regressions

Disable Auto-Updates

If you need to prevent automatic updates (for compliance or stability reasons), set the environment variable:

export DISABLE_AUTOUPDATER=1

Add this to your ~/.bashrc to make it permanent:

echo 'export DISABLE_AUTOUPDATER=1' >> ~/.bashrc
source ~/.bashrc

Update Claude Code

Update procedures differ by installation method. Use the same approach you used for installation.

Update Native Installation

Native installations update automatically in the background by default. Check for updates manually:

claude update

Updates download in the background and take effect on the next restart of Claude Code.

Update Homebrew Installation

Homebrew installations do not auto-update. Check for updates periodically:

brew upgrade claude-code

Update npm Installation

Update the npm package to the latest version:

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

Consider migrating to the native installer by running /install-native from within Claude Code to gain automatic updates.

Troubleshooting

Command Not Found After Installation

If claude returns “command not found” after installation, the binary location is not in your PATH.

For native installations, verify the binary exists:

ls -la ~/.local/bin/claude

If the file exists, add the directory to your PATH:

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

Verify the command is now accessible:

claude --version

Search Features Not Working

If search, @file mentions, or slash commands fail, ripgrep may not be functioning correctly. Install the system ripgrep package:

sudo apt install ripgrep

Then set the environment variable to use the system version instead of the bundled one:

echo 'export USE_BUILTIN_RIPGREP=0' >> ~/.bashrc
source ~/.bashrc

Authentication Errors

If authentication fails or becomes stuck, reset the authentication state:

# From within Claude Code
/logout

# Then restart Claude Code and authenticate again
claude

If problems persist, remove the stored configuration and force a clean login. Claude Code stores authentication data in ~/.claude.json and session data in ~/.claude/:

rm -f ~/.claude.json
claude

For a complete reset that clears all session history and cached data:

rm -f ~/.claude.json
rm -rf ~/.claude
claude

Node.js Version Error (npm Installation)

If you see “Claude Code requires Node.js version 18 or higher”, verify your Node.js version:

node --version

If the version is below 18, upgrade Node.js using the NodeSource repository or nvm. Alternatively, switch to the native installer which does not require Node.js.

High Memory or CPU Usage

If Claude Code consumes excessive resources:

• Use /compact regularly to reduce context size
• Restart Claude Code between major tasks
• Add large build directories (node_modules, dist, build) to .gitignore so Claude Code skips them during indexing

Run Diagnostics

The built-in diagnostic tool checks your installation health:

claude doctor

This reports your installation type, version, and any detected issues.

Remove Claude Code

Remove Claude Code using the same method you used for installation.

Remove Native Installation

Remove the binary and data directories:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Verify removal:

claude --version

bash: claude: command not found

Remove Homebrew Installation

brew uninstall --cask claude-code

Remove npm Installation

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

Remove Configuration Files (Optional)

Claude Code stores configuration and session data in your home directory. Remove these files only if you want to completely reset your configuration:

This permanently deletes all Claude Code configuration, session history, and project memory files. Back up any custom configurations you want to preserve before proceeding.

rm -rf ~/.claude
rm -f ~/.claude.json

To remove project-specific Claude Code files from a repository:

rm -rf .claude
rm -f .mcp.json

Conclusion

Claude Code is now installed and configured on Ubuntu, enabling AI-assisted development directly from your terminal. The native installer provides the most streamlined experience with automatic updates, while npm and Homebrew offer alternatives for users with specific workflow requirements.

To get started with your first project, navigate to your codebase directory and run claude. Use /init to create a CLAUDE.md file that gives Claude Code context about your project structure and coding conventions. For ongoing maintenance, use /doctor to check installation health and /compact to manage context size during long sessions.