Guides · October 29, 2026

How to install Claude Code — one command, then your first session

The official Claude Code install commands for macOS, Windows and Linux, how to verify the install with claude --version and claude doctor, which plans can sign in, what to ask first, and how updates and uninstalling work. Checked against the official docs.

Claude Code: A Hands-On Guide · Part 1 of 10

Installing Claude Code takes one command. When people get stuck, it is usually not the install. It is the plan they signed in with or their PATH. This guide covers the official install commands, how to check the install, the first things to ask, and how to update or remove it. It was written by AI (Claude) and checked against the official Quickstart and Advanced setup docs. At hiio, we run our apps, site and marketing with Claude Code installed on a Mac using the official native installer.

Requirements

The most common mistake: the free claude.ai plan cannot use Claude Code. The official docs say so directly. You can sign in with a Console account (prepaid credits) instead of a subscription, but then you pay for what you use.

Install: pick the one line for your system

The recommended method is the native install. Open a terminal and paste one command.

macOS, Linux, WSL:

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

Windows PowerShell (your prompt shows PS C:\):

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

Windows CMD (your prompt shows C:\ without PS):

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

The installer shows no progress while it downloads. It may look stuck. Wait for it to finish. You do not need admin rights.

Other install methods

The Homebrew cask claude-code is the stable channel, about a week behind. claude-code@latest is the newest release. If you install with npm, the official docs warn: do not use sudo.

On Windows

You can run Claude Code natively on Windows or inside WSL. If Git for Windows is installed, Claude Code runs shell commands through Git Bash. If not, it uses PowerShell. Sandboxing, which isolates command execution, only works in WSL 2.

Verify the install

Open a new terminal window and run:

claude --version

If it prints a version like 2.1.xxx (Claude Code), you are done. If you get command not found, the install directory is not on your PATH yet. Follow "Fix your PATH" in the official installation troubleshooting guide.

For a deeper check:

claude doctor

It shows install health, settings-file errors and auto-update status, read-only, without starting a session. Run it first whenever something looks wrong.

First run and sign-in

Go to the project folder you want to work in and start Claude Code:

cd /path/to/your/project
claude

The first time, it asks you to log in. Follow the prompts in your browser. You only do this once. To switch accounts later, type /login inside a session.

What to try in your first session

The official quickstart suggests asking before changing anything:

1. what does this project do? Claude reads the files on its own and summarizes them. You do not need to paste files in.
2. explain the folder structure and where is the main entry point?
3. One small edit: add a hello world function to the main file. If it asks before making the change, select Yes.
4. /init. Claude looks through the code and writes a CLAUDE.md with build and test commands and project conventions. If a CLAUDE.md already exists, it suggests improvements instead of overwriting it (official docs: Memory).

CLAUDE.md is a note Claude reads at the start of every session. Use ./CLAUDE.md for one project and ~/.claude/CLAUDE.md for all your projects. We put things we would otherwise repeat every time, like "what to add at the end of commit messages," in this file.

Commands worth memorizing

Updating and uninstalling

The native install checks for new versions at startup and while running, installs them in the background, and applies them on the next launch. To update right away, run claude update. To get only the stable release (about a week behind), open /config and set Auto-update channel to stable.

To uninstall a native install on macOS or Linux:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

To also remove your settings and conversation history, delete ~/.claude and ~/.claude.json. This cannot be undone, so only do it if you want everything gone.

FAQ

Can I use Claude Code with a free Claude account?

No. According to the official docs, you need a Pro, Max, Team or Enterprise subscription or a Console (API) account. The free claude.ai plan does not include Claude Code.

What is the difference between the npm install and the native install?

The official docs say the npm package downloads and links the same native binary. The difference is the install location and how updates work. If you are new, the native install is simpler because it does not need Node.js.

Claude Code installed, but my terminal says "command not found: claude". How do I fix it?

The install directory is not on your PATH. First, open a new terminal window. If that does not help, follow the PATH section of the official installation troubleshooting guide. If claude doctor runs, it will also show other problems.

Is there a way to use Claude Code without the terminal?

Yes. You can also use the desktop app, the VS Code and JetBrains extensions, or the web at claude.ai/code. The official docs also have a terminal guide for people who have never opened a terminal.

Sources

• Claude Code docs — Quickstart
• Claude Code docs — Advanced setup
• Claude Code docs — Memory (CLAUDE.md)
• Claude Code docs — Troubleshoot installation
• Claude Code permission modes: all 6 explained
• How to create Claude Code subagents

#Claude Code#install Claude Code#claude doctor#CLAUDE.md#getting started

Written with AI (Claude) and checked against the linked sources.