How to Install Claude Code: Mac, Windows & Linux Guide

TL;DR: Claude Code installs as an npm package in under 5 minutes on Mac, Windows, or Linux. You need Node.js 18+ and active FreeClaude access. This guide covers installation for every platform, post-installation setup, your first session, essential commands, and troubleshooting common issues.

What is Claude Code?

Claude Code is Anthropic terminal-based AI coding assistant — and it is categorically different from browser-based AI tools or IDE plugins. Instead of pasting code snippets into a chat window and manually applying changes, Claude Code operates directly in your terminal with full access to your file system, shell commands, and development tools.

This means Claude Code can:

• Read your entire project structure and understand it before making any change
• Create, modify, and delete files directly on your machine
• Run your test suite, see the failures, and fix them automatically
• Execute git commands, build tools, and any shell command
• Make coordinated changes across dozens of files in a single session
• Create commits with meaningful messages that explain the reasoning behind changes

For professional developers, this transforms AI from a copy-paste helper into a genuine autonomous development partner. Features that previously took an afternoon can be implemented in 20 minutes through Claude Code agentic sessions.

Prerequisites

Before installing Claude Code, ensure you have the following:

If you do not have active FreeClaude access yet, visit freeclaude.io and complete your first referral to unlock downloads. The referral system is the only way to access Claude Code through FreeClaude.

macOS Installation

Step 1: Install Node.js (if needed)

Open Terminal (press Cmd + Space, type "Terminal", press Enter). Check if Node.js is already installed:

node --version

If you see a version number below 18.x or see "command not found", install Node.js using fnm (Fast Node Manager) — the recommended approach:

curl -fsSL https://fnm.vercel.app/install | bash

Close and reopen Terminal, then run:

fnm install --lts

Verify: node --version should now show 20.x or higher.

Step 2: Install Claude Code

With Node.js ready, install Claude Code globally via npm:

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

Alternatively, you can download the pre-compiled binary directly from the Downloads tab in your FreeClaude dashboard. The binary approach does not require Node.js but offers less flexibility for updates.

Step 3: Authenticate

Run claude in your terminal. On first launch, it will prompt you to authenticate with your FreeClaude credentials. Follow the on-screen instructions — typically a browser window opens for OAuth authentication, or you paste a token from your dashboard.

Apple Silicon (M1/M2/M3/M4) vs Intel

The npm installation method works identically on both architectures — npm detects your chip and installs the correct binary automatically. The pre-compiled binary approach provides separate downloads for Apple Silicon and Intel; your dashboard automatically serves the correct version based on your device detection.

Windows Installation

Step 1: Install Node.js

Open PowerShell as Administrator (right-click the Start button, select "Windows PowerShell (Admin)").

Check for Node.js: node --version

If not installed, use winget (built into Windows 10/11):

winget install -e --id OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements

Close PowerShell completely and reopen it as Administrator. Verify: node --version

Step 2: Install Claude Code

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

If you encounter a PowerShell execution policy error, run this first:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Step 3: Windows Terminal Recommendation

For the best Claude Code experience on Windows, use Windows Terminal (available free from the Microsoft Store) with PowerShell 7. The classic Command Prompt works but has display limitations for Claude Code rich output formatting.

WSL (Windows Subsystem for Linux) also works well if you prefer a Linux-like development environment on Windows.

Linux Installation

Linux installation is typically the most straightforward since most development machines already have Node.js and a capable terminal.

Ubuntu/Debian

Check Node.js version: node --version

If below 18 or missing, install via NodeSource:

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

Then install Claude Code: sudo npm install -g @anthropic-ai/claude-code

Fedora/RHEL/CentOS

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs
sudo npm install -g @anthropic-ai/claude-code

Arch Linux

sudo pacman -S nodejs npm
sudo npm install -g @anthropic-ai/claude-code

Any Linux (via fnm)

curl -fsSL https://fnm.vercel.app/install | bash
Restart your shell, then:
fnm install --lts
npm install -g @anthropic-ai/claude-code

Post-Installation Setup

After installing, complete these steps before your first coding session:

1. Open a new terminal window — This is important. The new PATH entries added by the npm installation only take effect in new terminal sessions.
2. Verify installation — Type claude --version and confirm a version number appears.
3. Run initial authentication — Type claude and follow the authentication prompts. This connects Claude Code to your FreeClaude account.
4. Configure git (if not already done) — Claude Code creates commits on your behalf. Ensure git knows your identity: git config --global user.name "Your Name" and git config --global user.email "you@example.com"

Your First Claude Code Session

Navigate to a project you are working on and start Claude Code:

cd ~/my-project
claude

Claude Code launches and displays your account details and access status. For your first session, try these introductory prompts:

• "Read this project and give me a summary of the architecture, main components, and any immediate issues you notice"
• "Show me the test coverage and identify areas with no tests"
• "Find any TODO comments or console.log statements left in the code"
• "What dependencies are outdated and which updates would be safe to apply?"

These prompts give Claude Code the chance to familiarize itself with your project before you ask it to make changes — which generally produces better results than jumping straight into code modifications.

Essential Commands Reference

Configuration and Customization

Claude Code reads a CLAUDE.md file from your project root if one exists. This file acts as a persistent instruction set that Claude Code loads at the start of every session in that project. You can use it to specify:

• Project conventions, naming patterns, and code style preferences
• Testing requirements and coverage expectations
• Deployment procedures and infrastructure notes
• Team-specific context that Claude should always be aware of
• File paths that should not be modified

Run /init in any project to have Claude Code auto-generate an initial CLAUDE.md based on its analysis of your codebase. Review and refine it before committing.

Troubleshooting

"command not found: claude"

Close and reopen your terminal. If the issue persists, check that npm global bin directory is in your PATH:

npm config get prefix

Add the output path with /bin appended to your shell profile (~/.zshrc, ~/.bashrc, or equivalent).

"Authentication failed" or "Unauthorized"

Check your FreeClaude dashboard to confirm your access timer is active. If your timer has expired, invite another friend to extend it. If the timer is active but authentication still fails, try running claude logout followed by claude login to re-authenticate.

Slow responses or timeouts

Claude Code requires a stable internet connection to communicate with Anthropic servers. Check your connection quality. If on WiFi, try a wired connection for extended Claude Code sessions to avoid dropped connections mid-operation.

Permission errors when installing on Mac/Linux

Avoid using sudo npm install -g as it can cause permission issues. Instead, configure npm to use a user-writable directory:

mkdir ~/.npm-global
npm config set prefix ~/.npm-global
Then add export PATH=~/.npm-global/bin:$PATH to your shell profile.

Claude Code makes a change I did not want

Claude Code makes git commits incrementally. Run git log to see recent commits and git revert HEAD to undo the most recent commit. For larger sessions, Claude Code creates commits at logical checkpoints, making it easy to roll back to any prior state.

Frequently Asked Questions

Does Claude Code work offline?

No. Claude Code sends your code context to Anthropic servers for AI processing. A stable internet connection is required throughout all sessions.

Is my code sent to Anthropic when I use Claude Code?

Yes. The content of files Claude Code reads is sent to Anthropic API for processing. Anthropic privacy policy applies. Do not use Claude Code on files containing secrets, credentials, or highly sensitive proprietary information without reviewing Anthropic data handling policies for your use case.

Can I use Claude Code in a Docker container?

Yes, with standard Node.js Docker images. Install claude-code via npm in the container and mount your project directory as a volume.

What Node.js version does Claude Code require?

Node.js 18.0 or higher is required. Node.js 20 LTS or Node.js 22 LTS are recommended for the best experience.

How do I update Claude Code?

Run npm update -g @anthropic-ai/claude-code to update to the latest version. You can also run npm install -g @anthropic-ai/claude-code@latest to force a specific version install.

Can I use Claude Code in CI/CD pipelines?

Claude Code is designed for interactive developer use. For automated CI/CD use cases, the Anthropic API is more appropriate. However, some teams script non-interactive Claude Code sessions for specific review tasks in CI pipelines.

Need Help?

If you run into installation or usage issues not covered here, contact our support team via the FreeClaude Telegram bot. You can also visit our AI coding assistant comparison to understand why Claude Code leads the field, or our getting started guide if you need help activating your FreeClaude account first.

Advanced Configuration for Professional Workflows

Once Claude Code is installed and working, these configuration options significantly improve the experience for professional development workflows:

Creating a Global CLAUDE.md

In addition to project-level CLAUDE.md files, you can create a global Claude Code configuration at ~/.claude/CLAUDE.md. This file is loaded for every Claude Code session regardless of project and is ideal for personal preferences that apply universally:

• Your preferred code comment style
• Default programming language preferences
• Personal conventions for commit message format
• Reminder about tools you always want Claude to use (like running tests before committing)
• Any personal context about your development environment setup

Configuring Model Selection

Claude Code can be configured to default to a specific model using the --model flag or by setting it in configuration:

• claude --model claude-opus-4-7 — Use Opus for maximum capability
• claude --model claude-sonnet-4-6 — Use Sonnet for faster responses (recommended for most sessions)
• claude --model claude-haiku-4-5 — Use Haiku for lightweight quick tasks

You can also switch models mid-session with the /model command without losing conversation context.

Shell Aliases for Faster Startup

Add these aliases to your shell profile (~/.zshrc or ~/.bashrc) for faster Claude Code invocation:

• alias cc="claude" — Quick launch
• alias cc-fast="claude --model claude-sonnet-4-6" — Fast mode with Sonnet
• alias cc-deep="claude --model claude-opus-4-7" — Deep analysis with Opus
• alias cc-review="claude --print /review" — Non-interactive code review

Git Workflow Integration

Claude Code integrates deeply with git workflows. Here are the patterns that experienced users rely on:

Feature Branch Workflow

Always start a Claude Code session for significant work by creating a new branch:

1. Create branch: git checkout -b feature/my-feature
2. Start Claude Code: claude
3. Describe the feature and let Claude Code implement it
4. Review the diff: git diff main
5. Merge when satisfied: git checkout main && git merge feature/my-feature

This workflow gives you complete control over what merges to your main branch while allowing Claude Code to work freely in the feature branch environment.

Using Claude Code for Code Review

Run claude on any branch and use the /review command to get a comprehensive review of all uncommitted changes. This is particularly valuable as a pre-commit check to catch issues before they are pushed to your repository.

Interactive Rebase Assistance

Ask Claude Code to help clean up messy commit histories: "I have 12 commits on this branch from exploration and false starts. Please squash them into 3 logical commits with clear messages describing what each group of changes accomplishes." Claude Code analyzes the commits and provides the git rebase commands needed to restructure them cleanly.

Using Claude Code Alongside Your IDE

Claude Code and your IDE are not mutually exclusive — they are complementary tools that work best in combination:

• IDE for: Active coding, syntax highlighting, autocomplete, debugging with breakpoints, visual file exploration, and UI-based git operations
• Claude Code for: Multi-file refactoring, implementing features from natural language descriptions, autonomous bug fixing, test generation, documentation, and understanding unfamiliar parts of large codebases

A common workflow: use your IDE for active feature development, switch to Claude Code when you hit a complex problem or need to make coordinated changes across multiple files, then return to your IDE to review and continue developing on Claude implementation. The two tools never conflict because Claude Code operates on your actual file system — changes made in Claude Code appear immediately in your IDE editor.

Optimal Workspace Setup for Claude Code Sessions

Professional developers who use Claude Code intensively have converged on workspace setups that maximize productivity:

• Split terminal layout — Run Claude Code in one terminal pane, keep a second pane for running your app, tests, or monitoring logs. Watch test results appear as Claude Code fixes bugs in real time.
• Git diff in IDE alongside terminal — Keep your IDE open to the source control diff view. As Claude Code modifies files, you see the changes highlighted in real time in your IDE without interrupting the Claude Code session.
• Tmux or iTerm2 session persistence — Use a terminal multiplexer to keep Claude Code sessions alive across network interruptions and laptop lid-closes. This is particularly important for long autonomous sessions (30+ minutes) where connection drops would otherwise lose progress.
• Dedicated project directories — Keep your projects well-organized with clear directory names. Claude Code reads your directory structure as part of its project understanding, and clean organization helps it immediately understand project boundaries.