Claude Code Setup Guide for Mac, Windows, and Linux

Introduction

Claude Code brings AI-powered development directly to your terminal. Unlike web-based AI assistants where you copy and paste code back and forth, Claude Code lives in your development environment. It reads your files, understands your project structure, and makes changes directly to your codebase.

This guide walks you through installing Claude Code on any major operating system. Whether you're on a Mac, Windows PC, or Linux machine, you'll have Claude Code running in about five minutes. We'll cover the prerequisites, platform-specific installation steps, API key configuration, and how to verify everything works correctly.

By the end of this guide, you'll have Claude Code installed and ready to help you write, debug, and refactor code faster than ever before.

Requirements

Before installing Claude Code, make sure your system meets these requirements:

Node.js 18 or Higher

Claude Code is distributed as an npm package, which means you need Node.js installed on your system. Version 18 is the minimum supported version, but we recommend using the latest LTS (Long Term Support) release for the best experience. You can check your current Node.js version by running node --version in your terminal.

npm or Yarn

npm comes bundled with Node.js, so if you have Node.js installed, you already have npm. Alternatively, you can use Yarn if that's your preferred package manager. Either works perfectly fine for installing Claude Code.

Anthropic API Key

Claude Code uses Anthropic's API to power its AI capabilities. You'll need an API key from the Anthropic console. We'll cover how to get one later in this guide.

Terminal Access

You'll need access to a terminal or command-line interface. On Mac, use Terminal or iTerm. On Windows, use PowerShell, Windows Terminal, or Command Prompt. On Linux, use your distribution's default terminal emulator.

Mac Setup

Mac users have several options for installing Node.js and Claude Code. Here's the recommended approach:

Step 1: Install Node.js

If you don't have Node.js installed, the easiest method is using Homebrew. If you don't have Homebrew, install it first by visiting brew.sh.

# Install Node.js via Homebrew
brew install node

# Verify installation
node --version
npm --version

Alternatively, download the installer directly from nodejs.org. Choose the LTS version for stability.

Step 2: Install Claude Code

With Node.js installed, install Claude Code globally using npm:

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

Step 3: Configure Your API Key

Set your Anthropic API key as an environment variable. Add this line to your shell configuration file (~/.zshrc for Zsh or ~/.bash_profile for Bash):

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

After adding the line, reload your shell configuration:

source ~/.zshrc  # or source ~/.bash_profile

Step 4: Verify Installation

Test that everything works by running Claude Code:

claude --version
claude

If you see the Claude Code interface without errors, congratulations! You're ready to start using Claude Code on your Mac.

Windows Setup

Windows users can install Claude Code using PowerShell or Windows Terminal. Here's how to get started:

Step 1: Install Node.js

Download the Node.js installer from nodejs.org. Choose the LTS version, run the installer, and follow the prompts. Make sure to check the box that adds Node.js to your PATH.

Alternatively, if you use winget (Windows Package Manager), install Node.js from PowerShell:

# Install Node.js via winget
winget install OpenJS.NodeJS.LTS

# Restart PowerShell, then verify
node --version
npm --version

Step 2: Install Claude Code

Open PowerShell or Windows Terminal and install Claude Code globally:

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

Step 3: Configure Your API Key

Set your API key as an environment variable. You can do this through the Windows GUI or PowerShell:

# Set environment variable permanently
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "your-api-key-here", "User")

Restart PowerShell for the changes to take effect.

Step 4: Verify Installation

Test your installation:

claude --version
claude

Linux Setup

Linux installation varies slightly by distribution. Here are instructions for the most common setups:

Step 1: Install Node.js

The recommended approach is using Node Version Manager (nvm), which works across all distributions:

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

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

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

# Verify installation
node --version
npm --version

Alternatively, use your distribution's package manager:

# Add NodeSource repository for latest Node.js
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Node.js via dnf
sudo dnf install nodejs npm

Step 2: Install Claude Code

Install Claude Code globally with npm:

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

Step 3: Configure Your API Key

Add your API key to your shell configuration file (~/.bashrc, ~/.zshrc, or equivalent):

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

Reload your configuration:

source ~/.bashrc  # or your shell's config file

Step 4: Verify Installation

Confirm Claude Code is working:

claude --version
claude

Getting Your API Key

To use Claude Code, you need an API key from Anthropic. Here's how to get one:

Create an Anthropic Account

Visit console.anthropic.com and create an account if you don't have one. You can sign up with your email or use Google authentication.

Generate an API Key

Once logged in, navigate to the API Keys section in your dashboard. Click "Create Key" to generate a new API key. Give it a descriptive name like "Claude Code - Personal Laptop" so you can identify it later.

Pricing Overview

Anthropic charges based on token usage. Tokens are roughly equivalent to words, where 1,000 tokens equals approximately 750 words. Claude Code uses Claude's most capable models for reasoning about code.

For most individual developers, expect to spend between $10-50 per month depending on usage intensity. Heavy users working on large codebases may use more. You can set spending limits in the Anthropic console to avoid surprises.

New accounts typically receive free credits to get started, allowing you to try Claude Code before committing to a paid plan.

First Project Setup

Now that Claude Code is installed, let's set up your first project for optimal AI-assisted development.

Create a CLAUDE.md File

Every project should have a CLAUDE.md file in its root directory. This file tells Claude Code about your project's conventions, patterns, and specific requirements. Without it, Claude Code still works, but it won't understand your project's unique context.

# Project: My Web App

## Tech Stack
- React 18 with TypeScript
- Tailwind CSS for styling
- Firebase for backend

## Conventions
- Use functional components with hooks
- Follow the existing file naming pattern: kebab-case
- All components go in src/components/

## Important Notes
- Never modify files in src/generated/
- Always add tests for new features

Learn more about CLAUDE.md configuration in our comprehensive CLAUDE.md guide.

Run Claude Code

Navigate to your project directory and start Claude Code:

cd /path/to/your/project
claude

Claude Code launches in your terminal. You can now interact with it using natural language. Try starting with a simple request like "Show me the structure of this project" or "Explain what this codebase does."

Basic Commands

Here are some useful commands to get started:

• /help - Display available commands
• /clear - Clear the conversation history
• /exit or Ctrl+C - Exit Claude Code

IDE Integration

Claude Code works directly in your terminal, but you can also integrate it with popular code editors for a more seamless workflow.

VS Code

Use the built-in terminal in VS Code to run Claude Code. Open the integrated terminal with Ctrl+` (or Cmd+` on Mac) and run claude. This keeps Claude Code alongside your editor, allowing you to switch between asking Claude and reviewing changes in your files.

JetBrains IDEs

IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs have built-in terminal support. Open the terminal panel and run Claude Code from there. The IDE automatically detects file changes, so you'll see updates in real-time as Claude modifies your code.

Terminal-Based Editors

If you use Vim, Neovim, or Emacs, you can run Claude Code in a split terminal pane or use a terminal multiplexer like tmux. This setup keeps both your editor and Claude Code visible simultaneously.

Conclusion: Start Building with Claude Code

You've successfully installed Claude Code and configured it for your development environment. Whether you're on Mac, Windows, or Linux, you now have a powerful AI assistant ready to help you write better code faster.

Here's what to do next:

• Read the terminal guide: Learn essential commands and workflow patterns in our How to Run Claude Code in Terminal article.
• Set up your CLAUDE.md: Create project-specific configuration to get the most accurate help from Claude Code.
• Start small: Try asking Claude Code to explain existing code, fix a small bug, or add a simple feature before tackling larger tasks.

Claude Code works best when you treat it as a capable junior developer who needs clear, specific instructions. The more context you provide about what you want, the better results you'll get.