How to Set Up Claude Code on Mac and Windows: Complete Installation Guide
Install Claude Code on Mac or Windows step by step. Covers VS Code, Git, Node.js, permissions, and connecting your Claude subscription to get started fast.
What You Need Before You Start
Claude Code is Anthropic’s terminal-based AI coding tool. It runs in your command line, reads your codebase, and can write, edit, test, and run code on your behalf. Getting it installed takes about 15–20 minutes if you haven’t touched Node.js or Git before. Less if you have.
Before installing Claude Code, you need three things in place:
- Node.js v18 or later — Claude Code is distributed as an npm package and requires a recent Node version.
- A Claude subscription or Anthropic API key — You need either a Claude Pro/Max subscription or access through the Anthropic API to authenticate.
- Git (strongly recommended) — Claude Code works best when your project is version-controlled. If you’re new to Git, the version control explainer for non-developers is a good starting point.
A code editor is optional — Claude Code runs entirely in the terminal — but VS Code is the most common pairing and integrates cleanly.
How to Install Claude Code on Mac
Mac is the easier path. macOS ships with most of the underlying tools already present, and the Node.js ecosystem runs natively without any workarounds.
Step 1: Install Node.js
You have three options. Pick whichever fits your workflow.
Option A: Homebrew (recommended for developers)
If you use Homebrew, install Node with:
brew install nodeOption B: nvm (recommended for managing multiple Node versions)
nvm lets you switch between Node versions without conflicts. Install it with:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bashThen restart your terminal and run:
nvm install --lts
nvm use --ltsOption C: Official installer
Download the macOS installer directly from nodejs.org. Choose the LTS version (18 or higher). Run the .pkg file and follow the prompts.
After any of these, verify your installation:
node --version
npm --versionBoth should return a version number. If Node is below v18, upgrade before continuing.
Step 2: Install Claude Code
With Node in place, install the Claude Code package globally:
npm install -g @anthropic-ai/claude-codeThis pulls the @anthropic-ai/claude-code package from npm and makes the claude command available system-wide.
Verify it installed:
claude --versionStep 3: Handle macOS Permissions
On some Mac setups — especially newer machines with tighter security defaults — you may see a permissions error when running npm global installs. This usually looks like:
EACCES: permission denied, mkdir '/usr/local/lib/node_modules'The fix is to change the npm global directory to one you own, rather than running with sudo (which creates its own problems):
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'Then add the following to your ~/.zshrc or ~/.bash_profile:
export PATH=~/.npm-global/bin:$PATHReload your shell:
source ~/.zshrcNow retry the install command. It should complete without errors.
Step 4: Authenticate with Your Claude Account
Run:
claudeOn first launch, Claude Code will prompt you to authenticate. You’ll be given a URL to open in your browser. Log in with your Anthropic account (the one tied to your Claude Pro or Max subscription), and authorize the connection.
If you’re using the API directly instead of a subscription, you can set your API key as an environment variable:
export ANTHROPIC_API_KEY=your_key_hereAdd that line to your shell config file to persist it across sessions.
Step 5: Test Your Setup
Navigate to a project folder and run:
cd ~/your-project
claudeClaude Code will read your directory structure, and you’ll see a prompt where you can start giving it instructions. If it loads without errors, you’re good to go.
How to Install Claude Code on Windows
Windows requires a bit more setup. Claude Code is built for Unix-style environments, and while it can run natively on Windows, the recommended path is through Windows Subsystem for Linux (WSL2). This gives you a full Linux shell inside Windows and avoids a range of compatibility issues with line endings, file paths, and shell scripts.
Step 1: Enable WSL2
Open PowerShell as Administrator and run:
wsl --installThis installs WSL2 and sets Ubuntu as the default Linux distribution. Restart your machine when prompted.
After restarting, open the Ubuntu app from your Start menu. You’ll be asked to create a Linux username and password. These are separate from your Windows credentials — keep them simple and memorable.
If you already have WSL installed but aren’t on WSL2, upgrade with:
wsl --set-default-version 2Step 2: Install Node.js Inside WSL
Inside your Ubuntu terminal, install nvm (the Node version manager):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bashClose and reopen the terminal, then install Node:
nvm install --lts
nvm use --ltsVerify:
node --version
npm --versionYou want Node v18 or higher.
Step 3: Install Claude Code
Still inside your WSL terminal:
npm install -g @anthropic-ai/claude-codeVerify:
claude --versionStep 4: Set Up VS Code to Work with WSL (Optional but Recommended)
If you’re using VS Code, install the WSL extension from Microsoft. This lets VS Code open folders inside your Linux environment directly.
Once installed, open VS Code from your WSL terminal by navigating to your project folder and running:
code .VS Code will launch with the WSL remote connection active. Your integrated terminal will run inside WSL, which means Claude Code will work exactly the same as on Mac.
Step 5: Authenticate with Your Claude Account
Same as Mac. Run:
claudeFollow the browser link to authenticate your Anthropic account. The session token will be stored locally, so you won’t need to log in every time.
For API key authentication:
export ANTHROPIC_API_KEY=your_key_hereAdd this to your ~/.bashrc to persist it:
echo 'export ANTHROPIC_API_KEY=your_key_here' >> ~/.bashrc
source ~/.bashrcA Note on Native Windows (Without WSL)
It’s possible to run Claude Code natively on Windows without WSL using PowerShell or Command Prompt. Install Node via the official Windows installer, then run the same npm install command.
In practice, native Windows installs run into more friction: path separators behave differently, some shell commands Claude Code issues won’t work in PowerShell, and certain file permission operations fail silently. WSL2 removes most of these headaches. If you’re starting fresh, WSL2 is worth the 10 minutes it takes to set up.
Connecting Your Claude Subscription
Claude Code’s capabilities depend on your subscription tier. Here’s what matters:
- Claude Pro — Access to Claude Code with standard usage limits. Fine for most individual use.
- Claude Max — Higher usage limits. Better suited if you’re running long sessions or complex multi-file tasks.
When you authenticate through the browser flow, Claude Code reads your account permissions automatically. You don’t need to configure anything manually.
If you’re working with the Claude Code Ultra Plan, you’ll have access to higher context windows and more compute-intensive tasks. That guide covers what’s included and when it’s worth the upgrade.
For teams or API-first setups, you can also authenticate using a key from the Anthropic Console. This is common when running Claude Code in CI/CD pipelines or on remote servers. Check out how to keep Claude Code running 24/7 without a local machine if you want to go that route.
First Steps After Installation
Once Claude Code is running, a few things are worth doing before you start your first real task.
Create a claude.md File
The claude.md file is a persistent instruction document that Claude Code reads at the start of every session. You put it in the root of your project, and it tells Claude about your codebase, conventions, and preferences — so you don’t have to repeat yourself every time you open a new session.
This is one of the more important things to get right early. There’s a full guide on how to write a claude.md file that actually works that covers the format and what to include.
Initialize Git in Your Project
If your project isn’t already a Git repo, initialize one:
git init
git add .
git commit -m "initial commit"Claude Code can read your Git history, propose commits, and use branches when making changes. It works without Git, but you lose a lot of safety net. Claude can rewrite files. Having commits to fall back on matters.
Understand the Permission Model
By default, Claude Code will ask for confirmation before running commands or making file changes. This is intentional. You can see what Claude wants to do before it happens.
If you want Claude to operate more autonomously without approvals on every step, look into Claude Code Auto Mode — it’s designed as a safer alternative to fully bypassing permissions, giving you more flow without fully removing guardrails.
Troubleshooting Common Installation Issues
claude: command not found after install
This usually means the npm global bin directory isn’t in your PATH. Run:
npm config get prefixTake the path it returns, append /bin, and add that to your PATH in your shell config file.
Authentication loop or browser link doesn’t work
Try running:
claude auth logout
claude auth loginIf you’re behind a corporate proxy or firewall, the OAuth redirect may be blocked. In that case, use the API key authentication method instead.
Node version too old
Claude Code requires Node v18 or higher. If you installed Node a while back and haven’t updated, run:
nvm install --lts
nvm use --ltsOr reinstall from the official site.
Windows: \r\n line ending errors
This is a classic WSL/Windows compatibility issue. Make sure you’re working inside your WSL filesystem (~/projects/...) rather than mounting Windows drives (/mnt/c/...). File operations on mounted Windows drives are slower and more prone to line ending issues.
npm EACCES permission errors on Mac
Follow the npm-global directory fix outlined in Step 3 of the Mac install section above. Do not use sudo npm install -g — it creates file ownership problems that are harder to fix later.
What to Do Once It’s Working
Getting Claude Code installed is the beginning. The tool gets more useful as you learn how to direct it well.
A few things worth exploring next:
-
Effort levels — Claude Code lets you set how hard it works on a task. The guide to Claude Code effort levels explains when to use low, medium, high, and max — and why using max for everything burns through your context fast.
-
MCP servers — Model Context Protocol servers let Claude Code read and write to external services: databases, APIs, spreadsheets, and more. If that’s relevant to your work, how to use MCP servers with Claude Code is the place to start.
-
Workflow patterns — Claude Code can operate in very different modes depending on what you’re building. The five Claude Code workflow patterns overview goes from simple sequential tasks to fully autonomous operation.
-
Context management — Long sessions accumulate context, and that affects both cost and performance. Understanding how the context window works in Claude Code helps you structure sessions so Claude stays focused and doesn’t drift.
If you’re curious how Claude Code compares to other AI coding tools, the Cursor vs Claude Code breakdown covers the fundamental difference in how each tool approaches your codebase.
Where Remy Fits
Claude Code is a powerful tool for developers who want an AI agent working directly in their existing codebase. But the setup you just went through — Node, Git, WSL, auth, permissions — gives you a sense of the overhead involved before you’ve written a single line.
Remy is built on a different premise. Instead of starting from code and using AI to help you write more of it, Remy starts from a spec: a structured markdown document that describes what your app does. From that spec, it compiles a full-stack application — backend, database, auth, frontend, deployment — without requiring you to manage a local environment at all.
The editor, terminal, AI agent, and live preview are all in the browser. There’s no Node version to manage, no PATH to configure, no WSL to set up. You describe the app, and Remy builds it.
That’s a different abstraction level than Claude Code. If you’re an engineer who wants AI help inside your existing project, Claude Code makes sense. If you want to go from idea to deployed full-stack app without the setup overhead, try Remy at mindstudio.ai/remy.
Frequently Asked Questions
Does Claude Code work on Windows without WSL?
Yes, but with limitations. Native Windows support exists and the basic install works through PowerShell. In practice, some shell commands fail because Claude Code expects a Unix-style environment. File paths, line endings, and certain command-line operations cause friction. WSL2 removes most of these issues and is strongly recommended for anything beyond basic usage.
Do I need a paid Claude subscription to use Claude Code?
You need either a Claude Pro or Max subscription, or access through the Anthropic API with a funded account. Claude Code does not work on the free Claude tier. If you want to run Claude Code without a paid Anthropic subscription, there’s a guide on running Claude Code for free using Ollama and OpenRouter that covers the alternative route.
Can I use Claude Code inside VS Code?
Claude Code runs in a terminal, not as a VS Code extension. But you can open VS Code’s integrated terminal and run Claude Code there. On Windows with WSL, use the WSL extension so your terminal connects to the Linux environment where Claude Code is installed. Some developers run Claude Code in a separate terminal window alongside VS Code, switching between them as they work.
What’s the difference between Claude Code and GitHub Copilot?
They work at different layers. Copilot is an inline suggestion tool — it completes code as you type. Claude Code is an AI coding agent that reads your entire codebase, reasons about it, and takes multi-step actions: editing multiple files, running tests, fixing errors, and proposing commits. The Claude Code vs GitHub Copilot comparison goes into the specifics.
How much does Claude Code cost to run?
Claude Code itself has no separate price. You pay through your Claude subscription or Anthropic API usage. On Claude Pro ($20/month), you get a fixed usage allowance. On the API, you pay per token consumed. Complex tasks and long sessions consume context quickly, which affects cost. The token management guide for Claude Code explains how sessions drain your context and what to do about it.
Is Claude Code safe to use in a production codebase?
Claude Code can read, write, and delete files, and can run terminal commands. It asks for confirmation before most actions by default. For production work, using it on a separate branch and reviewing changes before merging is the right practice. Keeping Git initialized in your project means you always have a rollback point if something goes wrong.
Key Takeaways
- Claude Code requires Node.js v18+, a Claude subscription or API key, and Git. Install these before the main package.
- On Mac, use Homebrew or nvm for Node. Fix npm permission errors by setting a custom global directory — don’t use
sudo. - On Windows, WSL2 is the recommended path. It eliminates most compatibility issues and gives you a proper Unix environment.
- Authentication uses a browser-based OAuth flow. API key auth is available for headless and server setups.
- The
claude.mdfile and Git initialization are both worth setting up immediately after install — they shape how useful Claude Code is on real projects. - If you want to skip the local environment setup entirely and build full-stack apps from a structured spec, try Remy.
