Complete Claude Code Installation Guide: irm Script, npm Setup & https://claude.ai/install.ps1 Explained

Fred· AI Engineer & Developer Educator6 min read

Introduction

Claude Code is my go-to command-line tool for AI-assisted coding. Whether you're on Windows, macOS, or Linux, installation is straightforward with multiple options:

  • Native Binary (Recommended): curl -fsSL https://claude.ai/install.sh | bash for Linux/macOS
  • Windows PowerShell: irm https://claude.ai/install.ps1 | iex for Windows users
  • npm Global Install: npm install -g @anthropic-ai/claude-code for Node.js environments

This guide covers each installation method in detail, plus troubleshooting with the claude doctor command to diagnose and fix common issues.

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 claude doctor

The claude doctor command is your first stop for troubleshooting. It analyzes your installation and reports potential issues.

claude doctor

What claude doctor Checks

The claude doctor command inspects:

  • Installation method: Native binary, npm, Bun, or Homebrew
  • Version information: Current version and update status
  • Auto-update capability: Whether updates can be applied
  • Search functionality: If ripgrep is properly bundled/installed
  • Path configuration: Whether Claude is in your PATH correctly
  • Execution path: The actual binary being run

Common Problematic Outputs

Watch for these warning signs in claude doctor output:

  • unknown (2.0.0) - Version detection failed, likely mixed installation
  • Mixed paths between Bun, npm, and Node.js
  • Invocation path different from execution path
  • Auto-updates disabled or failing
  • Search status showing errors

Also check for multiple installations that may conflict:

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: npm install -g @anthropic-ai/claude-code

If you prefer using npm (Node Package Manager), you can install Claude Code globally. This method requires Node.js 18 or higher.

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

What npm install -g Does

The -g flag installs the package globally, making claude available as a command anywhere in your terminal. The package @anthropic-ai/claude-code is the official npm package maintained by Anthropic.

Benefits of npm installation:

  • Familiar workflow for Node.js developers
  • Easy to manage alongside other global packages
  • Works well in containerized/CI environments

Drawbacks:

  • Requires Node.js runtime
  • May conflict with other package managers (Bun, pnpm)
  • Updates require manual npm update -g @anthropic-ai/claude-code

Important: Never use sudo npm install -g as this causes permission issues. If you get EACCES errors, fix your npm permissions instead.

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: Using irm https://claude.ai/install.ps1 | iex

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 (Native Windows): 
    irm https://claude.ai/install.ps1 | iex

Understanding the irm Command

The irm command is PowerShell's Invoke-RestMethod, which downloads content from a URL. Here's what the command does:

  • irm https://claude.ai/install.ps1 - Downloads the installation script from Anthropic's servers
  • | iex - Pipes the script to Invoke-Expression, which executes it

The https://claude.ai/install.ps1 script handles:

  • Detecting your Windows architecture (x64, ARM64)
  • Downloading the appropriate Claude Code binary
  • Installing to your user directory
  • Adding Claude to your PATH environment variable

Security Note: Always verify you're downloading from the official claude.ai domain before running installation scripts.

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
Fred

Fred

AUTHOR

Full-stack developer with 10+ years building production applications. I use Claude Code daily for development and know its strengths and limitations.