45  45. Installing Claude Code

This page gets Claude Code onto your computer, logs you in, and checks that everything works. It takes about ten minutes. Your first real working session is on the next page.

45.1 What you need

As of Oct 6, 2026 · Official docs: Advanced setup · Authentication

  • A supported computer. macOS 13.0 or later; Windows 10 version 1809 or later (or Windows Server 2019+); or a common Linux such as Ubuntu 20.04+. At least 4 GB of RAM, a 64-bit processor, an internet connection, and a location in one of Anthropic’s supported countries.
  • An account that includes Claude Code. A paid Claude subscription (Pro, Max, Team, or Enterprise) or a Claude Console account (the developer account that is billed per use of the API). The free claude.ai plan does not include Claude Code. Plans and prices are compared in Claude Models, Plans, and Usage Limits.
  • A terminal. Mac users use the Terminal app. Windows users should have Git for Windows installed (see Getting Bash on Your Computer). It is optional for Claude Code but recommended: it provides Git Bash, which Claude Code uses for its Bash tool (the tool Claude uses to run shell commands). Without it, Claude Code runs commands through PowerShell instead.
Prefer buttons to a terminal?

Claude Code also comes as a desktop app and in other places (see Claude Code Beyond the Terminal). This course uses the terminal version, because that is where you see exactly what Claude does.

45.2 Install Claude Code

As of Oct 6, 2026 · Official docs: Advanced setup · Terminal guide for new users

The recommended way to install is Anthropic’s native installer: a small script that downloads the claude program and keeps it up to date automatically.

  1. Open Terminal (Cmd+Space, type Terminal, press Enter).

  2. Paste this line and press Enter:

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

    curl downloads the installer from claude.ai, and the pipe | hands it to bash, which runs it. When it finishes you see Claude Code successfully installed!

  3. If the output also shows Setup notes saying that ~/.local/bin is not in your PATH, run the command shown there (the same fix is under Fixing common problems below). The installer does not change your PATH itself. Then close the Terminal window and open a new one.

The installer runs in PowerShell, not in Git Bash. (The curl ... | bash command on the Mac tab is for Mac, Linux, and WSL only.)

  1. Press Win+X and choose Windows PowerShell or Terminal. The prompt starts with PS, for example PS C:\Users\sam>. Do not pick an entry that ends in “(x86)”.

  2. Paste this line and press Enter (you do not need to run as Administrator):

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

    irm downloads the installer and iex runs it. When it finishes you see Claude Code successfully installed!

  3. If the output also shows Setup notes saying that the install folder is not in your PATH, add it first (see Fixing common problems below). Then close all terminal windows. From now on, open Git Bash to use Claude Code, like every other command in this book.

If your window is the older Command Prompt (CMD; the prompt has no PS), use this command instead:

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

Use the same command as on a Mac. If you use WSL (Linux inside Windows), run it inside your WSL terminal, and later start claude there too.

curl -fsSL https://claude.ai/install.sh | bash
Piping a download into a shell

Bash Scripts (and Using AI at the Command Line) warns you never to run curl ... | bash on something you don’t understand, because it runs a script from the internet with your permissions. This case is fine because it is the official installer published in Anthropic’s own documentation. Still, copy it from the official docs (or this page) and check that the address is exactly https://claude.ai/....

  • Homebrew (Mac): brew install --cask claude-code. This “cask” follows the stable release channel (typically about a week behind), and by default it does not update itself: run brew upgrade claude-code now and then.
  • WinGet (Windows, in PowerShell): winget install Anthropic.ClaudeCode. Also no automatic updates by default: run winget upgrade Anthropic.ClaudeCode.
  • npm: npm install -g @anthropic-ai/claude-code (needs Node.js 22 or later). Never use sudo with it. The native installer is preferred.
  • Linux package managers: signed apt, dnf, and apk repositories exist; see the setup docs.
  • Native Windows vs WSL: Claude Code runs natively on Windows (what this book uses) or inside WSL 2. Only WSL 2 supports Claude Code’s sandbox (see Permissions, Modes, and Safety).

45.3 Check that it worked

As of Oct 6, 2026 · Official docs: Advanced setup

Open a new terminal window (Git Bash on Windows) and run:

claude --version

Output:

2.1.291 (Claude Code)

Your number will probably be different (usually higher), because Claude Code updates often. For a fuller health check, run:

claude doctor

claude doctor prints read-only diagnostics about your installation and settings (problems found and suggested fixes) without starting a session. If either command says claude is not found, jump to Fixing common problems below.

45.4 Start Claude Code and log in

As of Oct 6, 2026 · Official docs: Authentication · Quickstart

Claude Code always works in a folder, so start it inside a project folder, not in your home directory. For now, make an empty practice folder:

mkdir -p ~/projects/claude-practice
cd ~/projects/claude-practice
claude

The first launch shows a few setup screens (their exact order and wording can change between versions):

  1. Pick a color theme with the arrow keys and Enter.
  2. Log in. Choose your account type (a Claude subscription or a Console account). A browser window opens; sign in there. If the browser doesn’t open, press c to copy the login address and paste it into your browser. If the browser shows a code instead of sending you back, paste the code into the terminal where it says Paste code here if prompted. When you see Login successful, press Enter.
  3. Trust the folder. Claude Code asks whether you trust the files in this folder. Answer yes for your own folders (more on this on the next page).

You are now at the Claude Code prompt. Type /exit and press Enter to leave for now.

Your login is saved (in the macOS Keychain on a Mac, in a credentials file inside C:\Users\sam\.claude on Windows), so you won’t log in every time. Inside a session, /login switches accounts and /logout signs you out.

Watch out for an old ANTHROPIC_API_KEY

If the environment variable ANTHROPIC_API_KEY is set on your computer (see Environment Variables), Claude Code asks once whether to use that key. If you say yes, it uses the key, and your usage is billed to that API account instead of your subscription. Run /status inside Claude Code to see which login is active. To go back to your subscription, run unset ANTHROPIC_API_KEY and delete the export line from your ~/.zshrc or ~/.bashrc.

45.5 Updating

As of Oct 6, 2026 · Official docs: Advanced setup

  • The native installer updates automatically in the background. A new version takes effect the next time you start claude.
  • To update right now, run claude update.
  • Homebrew and WinGet installs do not update themselves by default (see the deeper dive above).
  • By default you are on the latest release channel. You can switch to stable (about a week older, skipping releases with major problems) in /config under Auto-update channel.

Claude Code changes almost every week. When a tutorial (or an AI answer) does not match what you see, check your version and the changelog, as explained in Navigating the Claude Documentation.

45.6 Where Claude Code lives on your computer

As of Oct 6, 2026 · Official docs: Advanced setup · Troubleshoot installation and login

What Mac and Linux Windows
The claude program (launcher) ~/.local/bin/claude C:\Users\sam\.local\bin\claude.exe
The downloaded versions ~/.local/share/claude/ C:\Users\sam\.local\share\claude\
Your settings, session history, and more ~/.claude/ C:\Users\sam\.claude\
Global configuration file ~/.claude.json C:\Users\sam\.claude.json

All of these are hidden (their names start with a dot; see Files, Folders, and Paths). Projects can also have their own .claude folder; what goes in each folder is covered in The .claude Folders and Settings Files.

Remove the program and its downloaded versions:

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

(Homebrew installs: brew uninstall --cask claude-code.)

In PowerShell:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

(WinGet installs: winget uninstall Anthropic.ClaudeCode.)

Your settings and history stay behind in ~/.claude and ~/.claude.json. Deleting those (rm -rf ~/.claude and rm ~/.claude.json) removes all your settings, permission rules, MCP server configurations, and session history, so only do it when you really want a clean slate. The VS Code extension and the desktop app also use ~/.claude.

45.7 Fixing common problems

As of Oct 6, 2026 · Official docs: Troubleshoot installation and login

What you see What it means and what to do
command not found: claude (Mac), bash: claude: command not found (Git Bash), or 'claude' is not recognized (PowerShell) The shell can’t find the program: its folder isn’t on your PATH yet (Environment Variables). First open a new terminal window. If that doesn’t help, add the folder to your PATH (below).
'irm' is not recognized You are in CMD, not PowerShell. Open PowerShell, or use the CMD command.
The token '&&' is not a valid statement separator You ran the CMD command in PowerShell. Use the PowerShell command (the one starting with irm).
'bash' is not recognized ... or A parameter cannot be found that matches parameter name 'fsSL' You ran the Mac/Linux command in PowerShell. Use the Windows command.
syntax error near unexpected token '<', or a 403 error The download returned a web page instead of the installer: your country may not be supported, or a network or proxy is blocking it. Retry later, or try Homebrew/WinGet.
Claude Code does not support 32-bit Windows You opened “Windows PowerShell (x86)”. Open the entry without “(x86)”.
Anything else Run claude doctor, then check the troubleshooting page in the docs.

To add the install folder to your PATH:

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

In PowerShell, run these two lines, then close every terminal and open a new Git Bash window:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

As of Oct 6, 2026 · Official docs: Advanced setup · Tools reference

On Windows, Claude Code can run shell commands with two tools: the Bash tool (which uses Git Bash) and the PowerShell tool. With Git for Windows installed and a claude.ai or Console login, both are on by default, and Claude treats PowerShell as its main shell, so you may see Claude run PowerShell commands such as Get-ChildItem instead of ls. If you would rather have Claude stick to Bash (matching this book), you can turn the PowerShell tool off by setting CLAUDE_CODE_USE_POWERSHELL_TOOL to 0 in your user settings file, ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "0"
  }
}

If Claude Code reports that it can’t find Git Bash, set CLAUDE_CODE_GIT_BASH_PATH the same way, to the path of bash.exe (by default C:\Program Files\Git\bin\bash.exe). Settings files are explained in The .claude Folders and Settings Files.

Practice Questions

Easy

Question 1 · Multiple choice

Which of these accounts can not be used to log in to Claude Code?

  1. A Claude Pro subscription
  2. The free claude.ai plan
  3. A Claude Console (API) account
  4. A Claude Team subscription

b. The free claude.ai plan does not include Claude Code. Pro, Max, Team, and Enterprise subscriptions (a and d) include it, and a Claude Console account (c) works too, billed per use of the API.

Question 2 · Short answer

What command checks that Claude Code is installed, and what does a working installation print?

claude --version. A working installation prints a version number followed by (Claude Code), for example 2.1.291 (Claude Code).

Question 3 · True or false

Claude Code cannot run on Windows unless Git for Windows is installed.

False. Git for Windows is optional but recommended. With it, Claude Code uses Git Bash for its Bash tool. Without it, Claude Code runs shell commands through PowerShell instead.

Question 4 · Matching

Match each command with what it does.

Command What it does
1. claude --version A. Signs you out (typed inside a session)
2. claude doctor B. Installs a newer version right now
3. claude update C. Prints read-only diagnostics about your install and settings
4. /login D. Prints the installed version number
5. /logout E. Logs in or switches accounts (typed inside a session)

1 → D, 2 → C, 3 → B, 4 → E, 5 → A.

Note that claude --version, claude doctor, and claude update are typed at the normal shell prompt, while /login and /logout are typed inside a running Claude Code session.

Question 5 · Short answer

Name the hidden folder and the hidden file in your home directory where Claude Code keeps your settings, session history, and global configuration.

The folder ~/.claude/ and the file ~/.claude.json. Both are hidden because their names start with a dot, so you need ls -a to see them.

Medium

Question 6 · Write the command

Maria has a Mac. Write the command she types in Terminal to install Claude Code with the native installer.

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

curl downloads the installer script and | bash runs it.

Question 7 · Write the command

Sam has Windows. In which program should he run the installer, and what command does he type?

In PowerShell (not Git Bash, not CMD):

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

After it finishes, he closes his terminals and uses Claude Code from a new Git Bash window.

Question 8 · Find the bug

Sam pastes curl -fsSL https://claude.ai/install.sh | bash into PowerShell and gets A parameter cannot be found that matches parameter name 'fsSL'. What went wrong, and what should he do?

He ran the Mac/Linux install command in PowerShell. In PowerShell, curl is a different command that doesn’t understand the -fsSL options. He should run the Windows command in PowerShell instead: irm https://claude.ai/install.ps1 | iex.

Question 9 · Scenario

Sam types irm https://claude.ai/install.ps1 | iex and sees 'irm' is not recognized as an internal or external command. His prompt looks like C:\Users\sam>. What is going on, and what are his two options?

His prompt has no PS, so he is in CMD, not PowerShell, and CMD doesn’t know irm. He can either open PowerShell and run the same command there, or stay in CMD and run the CMD installer: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd.

Question 10 · Scenario

Maria installs Claude Code and, in the same Terminal window, types claude. She gets zsh: command not found: claude. What should she try first, and what should she do if that doesn’t work?

First, close the window and open a new terminal: a window that was already open keeps the PATH it started with. If claude is still not found, the install folder isn’t on her PATH yet (the installer’s Setup notes say so; it doesn’t change the PATH itself), so she adds it:

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

Then check with claude --version.

Question 11 · Short answer

Maria installed Claude Code with Homebrew (brew install --cask claude-code). Will it update itself? If not, what command updates it?

No. Homebrew installs don’t auto-update. She updates with brew upgrade claude-code. (Only the native installer updates automatically in the background. The claude-code cask also follows the stable channel, which is typically about a week behind the latest release.)

Question 12 · Multiple choice

You started claude for the first time and the browser didn’t open for the login. What can you do?

  1. Nothing; Claude Code only works if a browser opens automatically
  2. Press c to copy the login address and paste it into a browser yourself
  3. Reinstall Claude Code
  4. Run claude --version

b. Pressing c at the login prompt copies the login URL so you can open it in any browser. Reinstalling (c) or checking the version (d) doesn’t help with login, and (a) is wrong because the copy option exists exactly for this case.

Hard

Question 13 · Scenario

Last semester Maria added export ANTHROPIC_API_KEY=... to her ~/.zshrc for a class project. Now she has a Claude Pro subscription. On her first launch, Claude Code asks whether to use an API key. What happens if she says yes, how can she check which login is in use, and how does she switch back to her subscription?

If she approves the key, Claude Code uses that API key instead of her subscription, so usage is billed to the API account (and if that old key’s organization is disabled, requests may even fail). Inside Claude Code, /status shows which authentication method is active. To switch back she runs unset ANTHROPIC_API_KEY and deletes the export ANTHROPIC_API_KEY=... line from ~/.zshrc so it doesn’t come back in new terminals, then starts claude again.

Question 14 · Long answer

Explain, using the idea of the PATH variable, why the shell can’t find claude right after a successful install in some cases, and why opening a new terminal window is part of the fix.

When you type a command name, the shell searches the folders listed in the PATH environment variable, in order, for a program with that name. The installer puts the launcher in ~/.local/bin (Windows: C:\Users\sam\.local\bin). If that folder isn’t in PATH, the shell can’t find claude even though the file exists. The installer doesn’t change your PATH; its Setup notes tell you to add the folder yourself (a line in ~/.zshrc on a Mac, or the user PATH on Windows). A terminal window reads its PATH when it starts, so a window that was already open keeps the old PATH even after that change; a new window reads the updated one.

Question 15 · Compare

Compare installing with the native installer and with Homebrew/WinGet. Which one does the official documentation recommend, and what is the main practical difference for a student?

The docs recommend the native installer. Its main advantage is automatic background updates: you always have a recent version (it uses the latest channel by default). Homebrew and WinGet installs don’t update themselves, so you must remember to run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode; the Homebrew claude-code cask also follows the slower stable channel. Because Claude Code changes weekly, an outdated version is a common reason why your screen doesn’t match the docs.

Question 16 · Short answer

This book warns you not to run curl ... | bash commands you don’t understand. Why is curl -fsSL https://claude.ai/install.sh | bash acceptable, and what should you check before running it?

Piping a download into bash runs a script from the internet with your permissions, so it is only safe when you trust the source. This command is the official installer, published in Anthropic’s own documentation. You should copy it from the official docs (or a source that quotes them) and check that the address is exactly https://claude.ai/install.sh, not a look-alike site or a copy from a random forum.

Question 17 · Scenario

Sam (Windows, with Git for Windows installed) notices that Claude Code sometimes runs commands like Get-ChildItem instead of ls. Why does this happen, and what setting could he change if he wants Claude to use Bash?

On Windows, Claude Code has both a Bash tool (using Git Bash) and a PowerShell tool. With a claude.ai or Console login, the PowerShell tool is on by default and Claude treats PowerShell as its main shell, so it may use PowerShell commands such as Get-ChildItem. Setting the environment variable CLAUDE_CODE_USE_POWERSHELL_TOOL to 0 (for example in the env section of ~/.claude/settings.json) turns the PowerShell tool off, so Claude uses the Bash tool.

Question 18 · True or false

To remove Claude Code completely, including your settings and session history, it is enough to delete ~/.local/bin/claude.

False. ~/.local/bin/claude is only the launcher. The downloaded versions live in ~/.local/share/claude/, and your settings and history live in ~/.claude/ and ~/.claude.json (projects may also have their own .claude folder and .mcp.json). Deleting the settings removes all your permission rules, MCP configurations, and session history, so do it only on purpose.

Challenge

Question 19 · Hands-on

Install Claude Code on your own computer. Then (a) run claude --version and write down the version, (b) run claude doctor and note any warnings, (c) start claude in ~/projects/claude-practice, log in, and run /status to see which account and model you are using. Finally, list the files in your home directory with ls -a and find the .claude folder and .claude.json file.

A good answer reports the version number (for example 2.1.291 (Claude Code) or newer), any claude doctor warnings and what they suggested, and the account, login method, and model shown by /status. In the ls -a listing you should see .claude (a folder) and .claude.json (a file), which were created when you installed and first started Claude Code. If something failed, describe the error message and which row of the “Fixing common problems” table it matched.

© 2025-2026 Y. Rosenthal. All rights reserved.