Skip to content
AI Coding Flow
Back to articles
tutorialclaude-codeinstallation

How to Install Claude Code: Complete Step-by-Step Guide

Complete tutorial to install Claude Code on macOS, Linux, and Windows. From Node.js to first run, with solutions for common issues.

11 min read

How to Install Claude Code: Complete Step-by-Step Guide

Claude Code is a coding assistant that runs directly in your terminal. It reads your files, understands your project's context, and writes real code. Unlike browser-based chatbots, it works alongside you, right inside your development environment.

In this guide, you'll install everything from scratch -- even if you've never opened a terminal before. The whole process takes less than 15 minutes.

What You Need Before Starting

Before installing Claude Code, you need to have four things in place. Nothing complicated, but it's important to check each one before moving on.

A computer running macOS, Linux, or Windows

Claude Code works on all three operating systems. On macOS and Linux, installation is straightforward. On Windows, it runs inside WSL (Windows Subsystem for Linux) -- a free Linux environment built into Windows by Microsoft. We cover setup below.

It doesn't matter if your computer is new or old. If it runs one of these systems and can open a browser, it can run Claude Code.

Node.js 18 or higher

Node.js is the engine that runs JavaScript programs outside the browser. Claude Code is built with this technology. You don't need to know JavaScript -- think of Node.js as a silent prerequisite, something that needs to be there but that you won't interact with directly.

Installation is simple and we cover each operating system in detail in the following sections.

An Anthropic account with an active subscription

Claude Code requires a paid Anthropic plan. It doesn't work with the free tier of Claude. Current options:

  • Pro -- $20/month. Great for getting started and sufficient for most personal projects.
  • Max -- $100/month or $200/month. For heavy Claude Code usage, with more generous rate limits.

Create your account at console.anthropic.com before proceeding. Signup takes less than two minutes.

A terminal

The terminal (also called "command line" or "shell") is the program where you type text commands for the computer to execute. It's the interface developers use daily, and it's where Claude Code lives.

If you've never used a terminal, don't worry. You just need to know how to type commands and press Enter. Here's where to find it on your system:

  • macOS: Open Finder, go to Applications > Utilities > Terminal. Or press Cmd + Space, type "Terminal," and press Enter.
  • Linux: Search for "Terminal" in your app menu. On most distributions, the shortcut Ctrl + Alt + T also works.
  • Windows: After installing WSL (explained below), search for "Ubuntu" in the Start menu.

Installation on macOS

1. Install Node.js

The simplest way is to download the official installer from the Node.js website.

  1. Go to nodejs.org
  2. Click the LTS (Long Term Support) version button. This is the recommended stable version.
  3. Open the downloaded .pkg file and follow the installation wizard. Click "Continue" until it finishes.

To verify the installation, open Terminal and type:

node --version

You should see something like v22.x.x. Any version from v18 onward works.

Along with Node.js, the installer also sets up npm (Node Package Manager), which is the tool you'll use to install Claude Code in the next step.

Homebrew alternative: If you already use Homebrew (macOS package manager), you can install with a single command:

brew install node

2. Install Claude Code

With Node.js installed, run this command in your terminal:

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

Let's break this command down:

  • npm -- the Node.js package manager (comes bundled with Node.js)
  • install -- the command to install a package
  • -g -- the "global" flag, making Claude Code available from any folder on your computer
  • @anthropic-ai/claude-code -- the official Anthropic package name

Installation may take 30 seconds to a few minutes depending on your internet speed.

3. Verify the installation

claude --version

If you see a version number (something like 1.x.x), the installation is complete. Skip ahead to "First Run and Authentication."

Installation on Linux (Ubuntu/Debian)

1. Install Node.js

The Node.js version in default Ubuntu repositories is often too old for Claude Code. The most reliable approach is to use nvm (Node Version Manager), a tool that manages Node.js versions.

First, install nvm:

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

This command downloads and runs the nvm installation script. After it finishes, close and reopen your terminal so the changes take effect.

Now install the LTS version of Node.js:

nvm install --lts

nvm will download, compile (if needed), and configure everything automatically. Verify the installation:

node --version

You should see v22.x.x or similar. Along with Node.js, nvm also installs npm.

Why nvm? Beyond easy installation, nvm automatically resolves permission issues that often appear when installing global npm packages. If you want to avoid permission errors later, nvm is the way to go.

2. Install Claude Code

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

3. Verify the installation

claude --version

Installation on Windows (via WSL)

Claude Code doesn't run directly on Windows. It needs WSL (Windows Subsystem for Linux), which creates a full Linux environment inside Windows. It sounds complicated, but Microsoft has made it a single-command install.

1. Install WSL

Open PowerShell as administrator. To do this, right-click the Start menu and select "Terminal (Admin)" or "PowerShell (Admin)." Then run:

wsl --install

This command installs WSL 2 and the Ubuntu distribution automatically. The process may take a few minutes. When it finishes, restart your computer.

After restarting, Ubuntu will open automatically and ask you to create a username and password. Choose something simple that you can remember -- you'll need this password occasionally to install software.

Important: When you type your password in the Linux terminal, no characters appear on screen. This is normal -- it's a security feature. Just keep typing and press Enter.

2. Install Node.js in WSL

From this point on, all commands should be run inside the Ubuntu (WSL) terminal, not in PowerShell or Windows CMD.

Install nvm:

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

Close and reopen the Ubuntu terminal. Then install Node.js:

nvm install --lts

Verify:

node --version

3. Install Claude Code

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

4. Verify the installation

claude --version

Tip for Windows users: From here on, always use the Ubuntu (WSL) terminal when working with Claude Code. Your Windows files are accessible inside WSL at /mnt/c/Users/YourName/. However, for better performance, we recommend creating your projects inside the Linux file system (at ~/projects/, for example).

Alternative: Run Without Installing

If you just want a quick test without installing globally, use npx:

npx @anthropic-ai/claude-code

npx downloads and runs the package temporarily. Each time you run this command, it checks for a new version. It's handy for a quick test, but for regular use the global install is more practical because it starts faster.

First Run and Authentication

With Claude Code installed, it's time to connect your Anthropic account. You only need to do this step once.

1. Start Claude Code

Open your terminal and type:

claude

2. Authenticate via browser

On the first run, Claude Code will display a message asking for authentication. It will automatically open your default browser to the Anthropic login page.

  1. Log in with your Anthropic account (the one with the Pro or Max subscription)
  2. Click "Authorize" to grant Claude Code access to your account
  3. Return to your terminal -- it should now be connected automatically

If the browser doesn't open automatically (common in WSL environments), copy the URL shown in the terminal and paste it into your browser manually. After authorizing in the browser, the terminal will pick up the authentication within seconds.

3. Confirm it's working

After authenticating, Claude Code will display an interactive prompt waiting for your input. Type anything to confirm:

> Hello, confirm that you're working

If it responds with a message, congratulations. You're all set.

Initial Configuration

On first launch, Claude Code asks a few configuration questions. These are simple choices you can change later.

Theme selection

It asks which theme you prefer for displaying responses. Choose dark if your terminal has a dark background, or light if it has a light background. This doesn't affect functionality, only readability.

Permission mode

Claude Code can read files, run commands, and edit code on your computer. It asks how you want to control these actions:

  • Ask (recommended default) -- asks for your confirmation before each action. You see exactly what it wants to do and can approve or reject. Ideal for beginners.
  • Auto-allow -- executes actions automatically without asking. Faster, but requires you to trust what you're requesting. Recommended only for experienced users.

Start with Ask. As you gain confidence, you can switch to Auto-allow by typing /permissions inside a Claude Code session.

The CLAUDE.md file

CLAUDE.md is a special file you place at the root of your project. It works as an "instruction manual" for Claude Code. Every time you start a session in a project, it reads this file automatically.

In it, you describe things like the project's stack, coding conventions, important commands, and any rules Claude Code should follow. This is what makes it generate code that's consistent with the rest of your project.

We won't go deep here -- we have a dedicated article on how to create an effective CLAUDE.md that covers everything in detail.

Common Problems and Solutions

Installation is usually smooth, but some issues can come up. Here are the most common ones and how to fix them.

"command not found: node"

The system can't find Node.js. If you used nvm, the most common cause is the terminal not having loaded nvm's configuration. Close and reopen your terminal. Then run:

nvm use --lts

If you installed from the official website and still get this error, the installer may not have added Node.js to your system's PATH. Try reinstalling following the steps for your platform.

"command not found: claude"

npm installed Claude Code, but the terminal can't find the executable. First, confirm that the package was installed:

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

If the package shows up in the list, it's a PATH issue. The directory where npm installs global packages isn't in the system's search path. On Linux/macOS, add this to your ~/.bashrc or ~/.zshrc:

export PATH="$(npm config get prefix)/bin:$PATH"

Then reload the configuration file:

source ~/.bashrc

Permission errors with npm (EACCES)

If you get errors like EACCES: permission denied when installing globally, don't use sudo. Installing npm packages with sudo creates bigger permission problems down the road.

Instead, configure npm to install to a directory inside your user folder:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

Add the new directory to your PATH in ~/.bashrc or ~/.zshrc:

export PATH="~/.npm-global/bin:$PATH"

Reload the terminal and try installing again:

source ~/.bashrc
npm install -g @anthropic-ai/claude-code

Simpler alternative: Use nvm (described in the Linux section). When you install Node.js via nvm, it puts everything in user-owned directories, completely eliminating permission issues.

Node.js version too old

Claude Code requires Node.js 18 or higher. Check which version you have:

node --version

If it's below v18, update. With nvm, just run:

nvm install --lts
nvm use --lts

If you installed from the official website, download the LTS version again from nodejs.org and reinstall.

WSL not installed (Windows)

If the wsl --install command fails, check two things:

  1. Virtualization enabled in BIOS. WSL 2 requires hardware virtualization. Restart your computer, enter BIOS (usually by pressing F2, F12, or Del during startup), and look for "Virtualization Technology," "VT-x," or "SVM Mode." Enable the option and save.

  2. Windows is up to date. WSL 2 requires Windows 10 version 2004 or later, or Windows 11. Go to Settings > Update & Security to check.

OAuth authentication error

If the browser opens but authentication fails or the terminal doesn't recognize the login:

  1. Verify your Anthropic subscription is active at console.anthropic.com
  2. Try clearing browser cookies for Anthropic's domain and try again
  3. If you're behind a corporate VPN or proxy, try disconnecting temporarily -- some proxies interfere with the OAuth flow
  4. In WSL environments, if the browser didn't open, copy the URL manually and paste it in the Windows browser

Firewall or proxy blocking the connection

In corporate or educational networks, the firewall may block Claude Code. Check with your IT team that connections to api.anthropic.com are allowed.

If you use a proxy, configure the environment variables in your terminal before running Claude Code:

export HTTPS_PROXY=http://your-proxy:port
export HTTP_PROXY=http://your-proxy:port

To make this configuration permanent, add these lines to your ~/.bashrc.

Final Verification

To confirm everything is working correctly, run this command:

claude --version

This confirms the executable is accessible. Now create a test folder and start a session:

mkdir -p ~/claude-test && cd ~/claude-test
claude

Inside the session, make a simple request:

> Create a file called hello.txt with the content "Hello, Claude Code!"

If it creates the file, your installation is complete and functional. You can delete the test folder afterward:

rm -rf ~/claude-test

Keeping Claude Code Updated

Anthropic releases frequent Claude Code updates with new features and improvements. To update, run the same installation command:

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

npm detects the existing package and updates to the latest version. We recommend checking for updates every week or two.

Next Steps

With Claude Code installed and running, you can start building right away. We recommend continuing with:

References