Complete Guide to Installing Claude Code: From Broken to Beautiful

Introduction

Claude Code is my go-to command-line tool for AI-assisted coding. The installation is straightforward, just a bash command. This guide covers both the standard installation process and troubleshooting steps.

Recommended: Native Binary

As of 2025, there are several runtims Claude is available in, including node.js and bun.js. Anthropic recommends using the native binary installation. This method avoids package manager conflicts, and is the most stable.

Installing the Native Binary

1. Run the installation script:

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

2. Reload your shell configuration:

   source ~/.bashrc
   # or for zsh users:
   source ~/.zshrc

3. Verify the installation:

   claude --version
   claude doctor

That's it! Claude Code should now be installed at ~/.claude/bin/claude or ~/.local/bin/claude.

Troubleshooting: Fixing Broken Installations

If you're experiencing issues with Claude Code such as segmentation fault errors, you likely have a mixed or outdated installation. If you have been using Claude since the start like I have, you may have a node.js or bun.js versions installed, too. Here's how to fix that:

Diagnose Your Current Installation with doctor

First, check what's installed:

claude doctor

Common problematic outputs include:

• unknown (2.0.0) version numbers
• Mixed paths between Bun, npm, and Node.js
• Invocation path different from execution path

Also check for multiple installations:

which -a claude

Remove ALL Existing Installations

# Remove Bun installation
bun uninstall -g @anthropic-ai/claude-code
rm -f ~/.bun/bin/claude

# Remove npm/Node.js installation
npm uninstall -g @anthropic-ai/claude-code

# Remove any nvm-specific installations
# Check each nvm Node version you have
nvm list
# For each version, switch to it and uninstall
nvm use <version>
npm uninstall -g @anthropic-ai/claude-code

Step 3: Clear Configuration and Cache

Remove any lingering configuration files:

# Remove Claude Code config directories
rm -rf ~/.claude-code
rm -rf ~/.config/claude-code
rm -rf ~/.cache/claude-code

Step 4: Fresh Native Binary Installation

Now install the native binary:

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

Step 5: Verify the Fix

After installation, verify everything is working:

# Check version
claude --version

# Run diagnostics
claude doctor

A healthy installation should show:

• Version: native (2.0.x or higher)
• Config install method: native
• Auto-updates: enabled
• Search: OK (bundled)

Alternative Installation Methods

While the native binary is recommended, here are other options:

npm Installation (Node.js 18+ required)

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

Important: Never use sudo npm install -g as this causes permission issues.

Specific Version Installation

To install a specific version of the native binary:

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 2.0.22

Platform-Specific Instructions

macOS with Homebrew

brew install claude-code

Note: Homebrew installations auto-update independently of the brew directory.

Windows

For Windows users, you have three options:

1. WSL (Recommended): Install WSL and follow the Linux instructions
2. Git Bash: Use the native installer with Git Bash
3. PowerShell:

   irm https://claude.ai/install.ps1 | iex

Alpine Linux

Alpine and other musl-based distributions need additional dependencies:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0
curl -fsSL https://claude.ai/install.sh | bash

Post-Installation Setup

Authentication

After installation, authenticate Claude Code:

claude

You'll be prompted to choose your authentication method:

• Claude Console (default): For API access with billing at console.anthropic.com
• Claude Pro/Max: If you have a Claude subscription
• Enterprise: For AWS Bedrock or Google Vertex AI deployments

Basic Usage

Start using Claude Code:

# Navigate to your project
cd /path/to/your/project

# Start Claude Code
claude

# Get help
claude help

# Inside a session, use slash commands
/help    # Show available commands
/clear   # Clear conversation
/exit    # Exit Claude Code

Managing Updates

Auto-Updates

Claude Code automatically updates by default. Updates are checked on startup and applied in the background.

How to update Claude Code

claude update

Add this to your `.bashrc` or `.zshrc` to make it permanent.

## Common Issues and Solutions

### Issue: "Insufficient permissions to install update"

This typically happens with npm/Bun installations. Solution: Switch to native binary installation.

### Issue: "command not found: claude"

The PATH wasn't updated. Add to your shell configuration:

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

Issue: Search functionality not working

Usually fixed by the native installation, but if persisting:

# Install ripgrep manually
sudo apt-get install ripgrep  # Ubuntu/Debian
brew install ripgrep          # macOS

Best Practices

1. Always use the native binary unless you have specific requirements
2. Avoid sudo with any installation method
3. Keep auto-updates enabled for security and features
4. Run claude doctor after any installation or update
5. Clean up old installations before installing new versions

Conclusion

Remember: when in doubt, remove everything and start fresh with the native binary. It's the simplest, fastest, and most reliable way to run Claude Code.

Related Reading

Now that you have Claude Code installed, you might be interested in:

• The Future of AI in Coding - Understand the bigger picture of where AI coding tools like Claude are heading and why they're here to stay

Quick Reference

• Install: curl -fsSL https://claude.ai/install.sh | bash
• Check version: claude --version
• Diagnose: claude doctor
• Update: claude update
• Start: claude
• Help: claude help