Skip to main content

1.1 Environment Setup

This section walks you through installing Claude Code and its dependencies.

System Requirements​

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

RequirementDetails
Operating SystemmacOS 10.15+, Ubuntu 20.04+ / Debian 10+, or Windows via WSL2
GitVersion 2.0 or higher
RAM4GB minimum (8GB recommended)
InternetRequired for API calls to Claude

Step 1: Verify Git Installation​

Confirm Git is available:

git --version

If not installed:

macOS:

brew install git

Ubuntu/Debian:

sudo apt-get install git

Step 2: Install and Authenticate GitHub CLI​

The GitHub CLI (gh) makes it easy to clone private repositories and interact with GitHub from the command line. Claude Code can use it for Git operations.

Install GitHub CLI​

macOS:

brew install gh

Ubuntu/Debian:

sudo apt install gh

Authenticate with GitHub​

gh auth login

Follow the prompts to authenticate. Choose:

  • GitHub.com (unless you're using GitHub Enterprise)
  • HTTPS for the preferred protocol
  • Login with a web browser for the easiest authentication flow

Verify authentication:

gh auth status

You should see confirmation that you're logged in.

Step 3: Install Claude Code​

Install Claude Code using the native installer:

macOS / Linux / WSL:

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

Windows (PowerShell):

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

Homebrew (macOS/Linux):

brew install --cask claude-code

Verify the installation:

claude --version

You should see version information for Claude Code.

Already installed via npm?

The npm installation method (npm install -g @anthropic-ai/claude-code) is deprecated. To migrate to the native installer, run:

claude install

This switches you to the native binary with automatic background updates. Verify with claude doctor.

Step 4: Authenticate with Claude Code​

Claude Code requires a subscription or an API key. For the purposes of this program, you should prefer using a subscription unless directed otherwise.

Authenticating With A Subscription​

Launch Claude Code in your terminal

claude

If you're already signed in, run the login command to reconfigure how you're signed in. Otherwise, you'll be prompted with login options automatically.

/login

Select login option (1) "Claude account with subscription". You'll be prompted to sign in to your Claude subscription account via your browser.

Authenticating With An API Key Option A: Environment Variable​

Set the ANTHROPIC_API_KEY environment variable:

export ANTHROPIC_API_KEY="your-api-key-here"

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist across sessions.

Authenticating With An API Key Option B: Configuration File​

Claude Code can store your API key in its configuration. Run:

claude config set apiKey your-api-key-here
Getting an API Key

If you don't have an Anthropic API key:

  1. Go to console.anthropic.com
  2. Sign in or create an account
  3. Navigate to API Keys
  4. Create a new key and copy it securely

Step 5: Configure Git Identity (If Needed)​

Claude Code creates commits on your behalf. Ensure Git knows who you are:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Troubleshooting​

"command not found: claude"​

If you see this error after installation:

  1. Ensure ~/.local/bin is in your PATH
  2. Add it to your shell profile if needed:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For Zsh users, replace ~/.bashrc with ~/.zshrc.

WSL2-Specific Issues​

Ensure you're running commands inside WSL2, not Windows PowerShell or CMD. Your prompt should show a Linux path (e.g., ~/projects) not a Windows path (e.g., C:\Users\...).

Next Steps​

With Claude Code installed, proceed to the next section to verify everything works correctly and learn the basic commands.

Knowledge Check​

Question 1 of 6

1.1 Environment Setup Knowledge Check

Q1. You've just installed Claude Code on a fresh Ubuntu machine and run `claude`, but the shell says 'command not found'. Git and the GitHub CLI both work fine. What is the most likely cause?