How to install Claude Code on macOS, Windows and Linux

Short version: Claude Code installs with one command and takes about three minutes on a clean system. The trouble starts after the install, not during it, and almost all of it comes down to four things: the command is not found, you are in the wrong terminal, the permissions are wrong, or your plan is free

Below: all four install methods and what actually separates them, how to verify the install, how to connect it to your editor, and a breakdown of failures with the error text you will see on screen

What you are actually installing

Claude Code is a terminal program you hand an entire project folder to. The difference from the browser chat is not the model. It is what happens after your question: the agent opens files itself, edits them itself, runs the project itself, reads the error text itself and takes the next step

In a chat you work as a courier. Copy a chunk of code there, copy the answer back, explain what is in the neighbouring file. By the third file that stops being work and becomes moving text around

What you need before you start

Three things, and only one of them is technical

A system. macOS 13 or newer, Windows 10 build 1809 or newer, Ubuntu 20.04+, Debian 10+, Alpine 3.19+. Four gigabytes of RAM. A 2018 laptop clears this

A paid account. The free Claude.ai tier does not include Claude Code, and the documentation says so in plain words. Pro, Max, Team, Enterprise or a Console account billed by tokens all work

A supported country. Anthropic publishes the list. If your country is not on it, no amount of configuration fixes that, and pretending otherwise breaks the terms you agreed to at sign-up

Source: Claude Code documentation, System requirements

The one-command install

This is the default method, and for most people it is the right one

On macOS and Linux, open a terminal and run:

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

On Windows in PowerShell:

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

On Windows in the plain command prompt:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

The command downloads an installer and runs it. On a clean system that is two to three minutes, ninety seconds of which is the download

The other three methods and what separates them

There are four ways to install, and exactly one thing separates them: whether the install updates itself

Package manager. brew install --cask claude-code on macOS, winget install Anthropic.ClaudeCode on Windows, apt, dnf and apk packages on Linux. Convenient if you already live in a package manager and update everything at once

Global npm package. npm install -g @anthropic-ai/claude-code. Works, but needs Node installed, and Node on Windows likes to install itself somewhere that later needs administrator rights

One command. The method above

The shared property of the first two: installs through Homebrew, WinGet and system packages do not update themselves. The one-command install updates in the background. Models and the agent itself change often, and a three-month-old version starts behaving differently from what the current documentation describes. If you are not going to track updates by hand, take the one-command install

Verifying the install

Close the terminal completely and open a new one. This is not superstition: the installer appends a path to your shell config, and an already-open terminal does not re-read that file

Then:

claude --version

A version number should print. If it does, next:

claude doctor

This command inspects your environment and tells you what is missing. Start any troubleshooting here, not by pasting the error into a search box

Connecting it to your editor

The official extension installs from the agent itself. Open a terminal inside your editor and run:

claude

On first launch inside VS Code or an editor based on it, the agent offers to install the extension. Accept. After that the agent knows which file you have open and what is selected in it, and edits are shown as a familiar diff rather than a wall of text in the terminal

The same works in IntelliJ-based editors: PyCharm, WebStorm, IDEA

The first run

Go into your project folder and start the agent from there:

cd path/to/project
claude

The agent asks you to sign in: a browser opens, you confirm, the tab closes. Then it asks permission to read the folder. Grant only the folder you actually work in, not your entire home directory

Make your first question about the project rather than the code: "what is this project and what is it made of". The answer tells you whether the agent can see your files and understands what it is looking at

The project config file: do this immediately

The agent reads a CLAUDE.md file at the project root at the start of every session. Without it you explain the same things in every new conversation: how the project runs, where things are, what must not be touched

Create it right after installing. A minimal working version:

# Project name

What it is: a small services page with an enquiry form

## Running it

npm run dev, port 3000

## Do not touch

.env.local, it holds the keys. public/photos, those are the client's photos

## How I want you to work

Show me a plan first, then edit. Do not rewrite neighbouring files
without asking

Three sections: how it runs, what not to touch, how you want to work. The agent will figure out the rest by reading the files

This file pays for itself in the second session. The difference is immediate: without it, the first five minutes of every conversation go to "where is your X"; with it, the agent starts on the work

Permissions: what the agent may do unasked

On first launch the agent asks for folder permission. After that it asks for almost every action: read a file, write a file, run a command

Half an hour in, this gets irritating and the temptation is to allow everything. Do not: the agent runs commands on your machine as you, and "everything" includes deleting files

A sensible middle: allow reading and editing files inside the project without asking, and keep command execution behind confirmation. This lives in a settings file inside the project's .claude folder, and once configured it carries to your next project by copying

Commands worth never auto-approving: anything starting with rm, anything that pushes to a shared repository, and anything that touches a production database. An agent mistake in those three places costs more than the confirmations saved

Windows: WSL or not

If you are on Windows and plan to go past a first look, the answer is WSL

WSL is a real Linux inside Windows. It installs with one command in an administrator PowerShell:

wsl --install

Then a reboot, you pick a username and password, and you have an Ubuntu terminal. Claude Code installs into it with the Linux command

Why bother: nine out of ten instructions on the internet are written for macOS or Linux. In WSL they work as written; in PowerShell half the commands either do not exist or are named differently. What you save is not install time, it is hours of translation on every later step

When not to bother: if you know you are stopping after a first look, or if your project depends on Windows-only programs

Claude Code, Cursor or Codex

The question comes up right after installing, and the search results answer it with feature tables. The practical difference is elsewhere

Claude Code is a terminal. No window of its own, no editor of its own, it lives where you already work. Strong at long multi-step tasks where a dozen files have to be read without losing the thread

Cursor is an entire editor, a VS Code fork with a model built in. Strong at edits in the open file, when you are looking at the code and want a chunk changed in front of you. Weak in that it is another program with another set of settings and another account

Codex is OpenAI's agent, built closer to Claude Code in shape. The difference is the model and the limits, not the approach

There is no point taking all three. Practical advice: start with one, carry a first project through to a link that opens, and only then look at what was missing. You pick a tool by what gets in your way, not by a list of capabilities

The first hour after installing

An order that saves you an evening

One: make an empty folder and open the agent in it. Do not start with an old project of two hundred files; you will not be able to tell where the agent is wrong and where you are

Two: ask for one page with a heading and a button. One page, not a site. The task has to be small enough that you can see for yourself whether it worked

Three: ask it to run the page and open it in a browser. This is usually where the first environment failures surface, and an empty folder is the best place for them to surface

Four: break something on purpose. Delete a line, look at the error, show the error to the agent. It is the only way to learn how it behaves when things break, and breakage will take up half your time

Five: only now start a real project

What breaks

Written from actual failures, not from a list of possibilities

command not found: claude

The most common one. The program installed, but the terminal does not know where to look for it

First, close and reopen the terminal. That fixes most cases

If it does not, check where the agent landed:

ls ~/.local/bin/claude

If the file is there but the command is not found, the path never made it into your shell config. Append it:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

macOS defaults to zsh and ~/.zshrc. Most Linux systems default to bash and ~/.bashrc. Mixing them up is easy and looks identical from the outside: the command still is not found. Check with echo $SHELL

On Windows it works in one terminal and not another

Windows is three different terminals: command prompt, PowerShell and WSL. Installing in one does not make the command available in the other two

Decide up front where you are going to work. If you are heading further into development, take WSL. If you do not need WSL yet, install in PowerShell and stay in PowerShell

Permission error during the npm install

Looks like EACCES: permission denied. It means npm is trying to write to a system folder

Do not rerun it with sudo: that fixes it once and creates a second problem, files owned by the wrong user. The right fix is to point npm's global folder at your own:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Then install again

The agent starts but complains about the account

Two possibilities. Either the plan is free, in which case there is no access at all, or the browser sign-in never completed. The second is fixed by running claude and signing in again; the first is fixed only by a paid plan

It installed but never updates

Check how you installed it. Through Homebrew and WinGet you update by hand: brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode. Through the one-command install it updates itself

Source: Claude Code documentation, Troubleshoot installation

What it costs per month

Pro is twenty dollars a month, Max starts at a hundred. The difference is not the model, it is the limits: how many requests you get through in five hours before the agent asks you to wait

For someone building their first product in the evenings, Pro is enough. The limit is not really about volume, it is about the habit of asking the agent instead of thinking: ten short clarifications in a row burn through it faster than one properly stated task

Bill separately for the model if you work through Console by tokens: there you pay for volume, and the bill depends on how many files the agent read

How to know the install actually worked

Not by the command starting, but by getting a result. A checklist for the first evening:

• claude --version prints a version rather than an error
• claude doctor finds nothing wrong
• the agent opens from the project folder and answers a question about the project
• the editor extension shows edits line by line rather than as plain text
• you built a page, opened it in a browser and saw your own heading

Fail on the first and it is the path. On the second, the environment, and doctor will name it. On the third, folder permissions. On the fourth, the extension did not install; run the agent from a terminal inside the editor again. On the fifth, it is no longer installation, it is work, and that is where it starts

In short

• Install with one command: it is the only method that updates itself
• Close and reopen the terminal afterwards, or the command will not be found
• claude doctor diagnoses faster than searching the error text
• The editor extension installs from the agent, on first launch inside it
• On Windows, pick your terminal first: three terminals are three separate installs
• The free plan does not include access, and no configuration changes that