Installation and Usage

📚 Series Navigation: The previous article 01 · What is Claude Code explained clearly what it is and what it can do. This article takes you to actually install it on your computer, log in, run it, and thoroughly explain upgrades, uninstallation, and troubleshooting in one go. The next article 03 · How Claude Code Works lifts the lid to look at the agentic loop.

Here's a common embarrassing story. Many people, when installing Claude Code for the first time, casually search for an old tutorial, type npm install -g @anthropic-ai/claude-code, and get stuck on permission errors. In a panic, they use sudo—it gets installed, but subsequent automatic updates fail every day, and claude doctor shows a bunch of red errors. After tossing around for almost an hour, they realize: the official guide has long listed the native script as the preferred choice, and the npm path has more pitfalls. Something that could be done in 30 seconds with a single line of curl script was instead done taking the most winding, error-prone path.

Frankly, installing Claude Code itself is not hard; what's hard is that no one tells you which path is a pitfall. This article will clearly mark the right path for each platform so you don't repeat the same mistakes.

After reading this article, you will get:

• One command to install Claude Code on Mac / Windows / Linux / WSL (with expected output, so you can verify if it's successfully installed)
• Comparison of three installation methods (official script / package manager / npm) to know which one to choose
• Complete operations for login, upgrade, and uninstallation
• A "error → how to fix" quick reference table, covering 90% of the pitfalls beginners encounter

---

01 Three Things to Figure Out Before Installing

Don't rush to type commands. Too many people only discover "oh, this account can't be used" halfway through installation, wasting their effort. Confirm three things first.

First Thing: Is Your Computer Qualified

Claude Code doesn't demand much from your machine, but there are a few hard limits (based on official specs):

Item	Requirement
OS	macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+
Memory	4 GB+ available RAM
Processor	x64 or ARM64
Network	Internet connection required
Terminal	Bash, Zsh, PowerShell or CMD

For macOS below 13.0: You can install it, but it will crash when run, throwing errors like dyld: cannot load—older systems do not support the instructions used by the binary, and there is no workaround other than upgrading the OS (on machines stuck on macOS 12, it absolutely won't run; upgrading to 14 fixes it).

Second Thing: You Must Have a Usable Account

The rule beginners overlook the most: the free tier Claude.ai account cannot use Claude Code.

The official requirement is one of the Pro, Max, Team, Enterprise, or Console (API) accounts. Just because you chat happily on the web version of Claude doesn't mean your account can drive Claude Code—the free tier simply doesn't work.

For those wanting to use third-party models (DeepSeek, GLM, Minimax) to save money, put the account step on hold; article 05 specifically covers connecting to third-party models. This article assumes you use the official account.

Third Thing: Where Do You Plan to Use It From

There are three ways to use Claude Code: CLI (Command Line) has the most complete features and is closest to the original design intent; Desktop App doesn't require touching the terminal and is ready to use after download; Editor Integration (VS Code / JetBrains) blends into the existing development flow.

My suggestion: directly learn the CLI. This article is also based on the CLI—it is the most stable and versatile. Once you learn it, the Desktop App and editor plugins will just take a few minutes later (articles 08-10 will cover them). If you really resist the terminal, go to https://claude.com/download to download the Desktop App, and you can use it with a few clicks.

💡 One-sentence summary: Confirm three things before installing—sufficient OS version, account is paid tier or Console, choose CLI as the usage method. Only after passing these three hurdles should you type commands.

---

02 Install It: One Command Per Platform

Conclusion first: All platforms should prioritize the official installation script (officially called "Native Install", currently the most recommended). The biggest advantage is—it updates automatically in the background after installation, basically no more worrying about versions.

Analogy: Native Install is like installing an App from the App Store. Click "install", it downloads itself, installs itself, and updates itself in the background later; the old npm method is more like "download an installation package and manually click next"—it installs, but you have to update it yourself, and it's prone to permission issues.

macOS / Linux / WSL

Open the terminal, paste this line:

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

Tip for users in China: claude.ai and the download server downloads.claude.ai usually require a proxy to access stably. Turning on your proxy during installation can prevent more than half of the "stuck / timeout" errors.

Windows (Native, without WSL)

First confirm which terminal you are in—this is the point where Windows users stumble the most, PowerShell and CMD commands are different:

PowerShell (prompt looks like this PS C:\>):

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

CMD (prompt is C:\>, without the preceding PS):

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

How to distinguish? Look if the prompt starts with PS: if yes, it's PowerShell; if not, it's CMD. Running the CMD command with && in PowerShell will report The token '&&' is not a valid statement separator, and conversely, running irm in CMD will report 'irm' is not recognized—if you see these errors, just switch to the corresponding command.

Additionally, for the Windows native environment, it's recommended to conveniently install Git for Windows, which provides Git Bash for Claude Code; if not installed, it will fall back to PowerShell to run commands (it works, but some Bash scripts are restricted). WSL does not need it.

Choose WSL or Native on Windows?

If you do Linux toolchain development, or want to use the sandboxing feature, go with WSL. Official comparison table:

Option	What is needed	Supports sandboxing	When to use
Native Windows	Nothing (Git for Windows optional)	❌	Windows native projects and tools
WSL 2	Enable WSL 2	✅	Linux toolchains or to use sandboxing
WSL 1	Enable WSL 1	❌	Fallback when WSL 2 doesn't work

If you go with WSL, just run the curl script for macOS/Linux above in the WSL terminal—it's installing in WSL, not in PowerShell.

Don't Want to Touch the Terminal? There Are Other Paths

Besides the official script, there are a few alternative paths, compared below so you can choose as needed:

Installation Method	Command	Auto Update	My Suggestion
Official Script	curl ... | bash	✅ Auto in background	Preferred, worry-free
Homebrew (macOS)	brew install --cask claude-code	❌ Manual	Those already heavily using brew to manage software
WinGet (Windows)	winget install Anthropic.ClaudeCode	❌ Manual	Those accustomed to using WinGet
npm	npm install -g @anthropic-ai/claude-code	❌ Manual	Consider last, requires Node.js 18+ first

A few pitfalls to mention in advance:

• Homebrew has two casks: claude-code is the stable version (one week behind, skips versions with major regressions), claude-code@latest is the newest version, upgrading corresponds to brew upgrade claude-code / brew upgrade claude-code@latest respectively.
• WinGet does not auto-update: Needs periodic manual runs of winget upgrade Anthropic.ClaudeCode.
• Never use sudo with npm. The official documentation explicitly warns that sudo npm install -g will cause permission issues and security risks—this is exactly the most common pitfall mentioned at the beginning. If you encounter permission errors, the right solution is to switch to the official script. Upgrading with npm also requires npm install -g ...@latest, do not use npm update -g.

💡 One-sentence summary: Blindly choosing the official script is right, a single curl (or Windows' irm) resolves the battle, and it comes with background updates; npm is the worst policy, and never use sudo.

---

03 Verify If the Installation Was Successful

Don't rush to use it after installation, take ten seconds to verify. Open a new terminal window, type:

claude --version

The expected output is a version number, similar to (the numbers you see will update, which is normal):

2.1.81 (Claude Code)

Seeing the version number = installation successful. If it reports command not found: claude or 'claude' is not recognized on Windows, don't rush to reinstall—90% of the time PATH is not set properly (the installation directory did not enter the system search path), section 06 has the fix.

For more details, the official documentation also provides a health check command:

claude doctor

It will list the installation status, configuration, and the result of the last update. After installing on a new machine or encountering glitches, your first reaction should be to run claude doctor—it's much faster than guessing blindly.

💡 One-sentence summary: claude --version showing the version number means success; if anything seems off, claude doctor is your primary diagnostic tool.

---

04 Login: Let It Recognize You

The installed Claude Code is still an "unrecognizing" empty shell; it needs to be logged in and bound to an account to work. Launch it in your project directory:

claude

Upon first launch, it will automatically guide you to log in, or you can trigger it manually after entering the interface:

/login

Next, it pops up a browser page for you to authorize, and once authorized, you go back to the terminal and it's logged in. Credentials are stored locally, no need to log in again on the next launch. To switch accounts, just run /login again.

What If Login Gets Stuck

The most common one: The browser didn't pop up automatically, or you logged in via a remote server / WSL / SSH—the browser might open on another machine, and the callback cannot return. The official solution is very simple:

Press c at the login prompt interface to copy that string of OAuth URL, manually paste it into the browser to open, after logging in a code is displayed, and then paste the code back into the terminal.

When configuring Claude Code on a cloud server, it's easy to fall for this, waiting foolishly for a browser popup with no response—in a remote environment, you must take the "copy URL and open manually" path. If even pasting doesn't work, there's a more stable fallback command:

claude auth login

It reads the code you pasted from standard input, specifically curing terminals where interactive prompts fail to accept pastes.

A Hidden Major Login Pitfall

After logging in, it reports This organization has been disabled, but the subscription is clearly fine—there is a high probability that an old ANTHROPIC_API_KEY is left over in the shell configuration, which overrides your subscription credentials.

When there's an API key in the environment variables, Claude Code will prioritize using the key instead of the subscription. The solution is to clear it:

unset ANTHROPIC_API_KEY
claude

To permanently solve it, rummage through ~/.zshrc, ~/.bashrc, or ~/.profile, and delete the line export ANTHROPIC_API_KEY=.... After entering Claude Code, use /status to confirm which login method is currently being used.

💡 One-sentence summary: Launching claude will automatically guide you to log in, in remote/WSL environments remember "press c to copy URL and open manually"; if login reports organization disabled, first check if there's a leftover old API key in the environment variables.

---

05 Upgrade and Uninstallation

Upgrade

If installed with the official script, you don't need to do anything—it updates automatically in the background, and the next launch will be the new version. If you want to update immediately:

claude update

To see if the update succeeded, it's still the claude doctor phrase. The update channel is selectable (written in settings.json, or set via /config inside Claude Code):

{
  "autoUpdatesChannel": "stable"
}

• "latest" (default): Get new features as soon as they are released
• "stable": Use a version from about a week ago, skipping releases with major regressions—choose this for stability pursuit

If you don't want automatic updates, just set "DISABLE_AUTOUPDATER": "1" in the env of settings.json (it only stops background checks, claude update manual update still works). Installations via Homebrew / WinGet / apt do not auto-update by default, you have to manually run the corresponding upgrade command (mentioned in the pitfall tips earlier).

Uninstallation

Correspond to your original installation method for uninstallation. Installed by official script:

macOS / Linux / WSL:

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

Windows PowerShell:

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

Other methods correspond respectively: Homebrew uses brew uninstall --cask claude-code, WinGet uses winget uninstall Anthropic.ClaudeCode, npm uses npm uninstall -g @anthropic-ai/claude-code.

Note: The above only deletes the program itself; configurations, authorizations, and session history remain in ~/.claude/. If claude can still run after uninstallation, most likely you have a second installation or a shell alias left from an old version (section 06 teaches you to uncover it).

To clean up completely (this step is irreversible, settings / authorization / MCP configs / session history will all be gone):

# Global user settings and state
rm -rf ~/.claude
rm ~/.claude.json

# Local settings for the current project (execute inside the project directory)
rm -rf .claude
rm -f .mcp.json

Reminder: VS Code extension, JetBrains plugin, and Desktop App also write things to ~/.claude/, if they are still installed this directory will be recreated—to delete completely you must uninstall them first.

💡 One-sentence summary: Upgrades for the official script installation rely on auto in the background, claude update to urge manually; uninstallation follows how it was installed, configuration files must be deleted separately, and deletion is irreversible.

---

06 Error Quick Reference: Pitfalls 90% of Beginners Hit

Encountering errors when installing this thing is basically unavoidable, but the vast majority have standard solutions. Compiling the most frequent categories from official docs into a quick reference table—identify the symptom first, then prescribe the medicine, don't just reinstall upon seeing an error.

Error You See	Real Reason	How to Fix
command not found: claude	Installation directory not in PATH	Add ~/.local/bin to PATH (see below)
syntax error near unexpected token '<'	Installation script returned HTML instead of script	Mostly network/region issue, use Homebrew/WinGet or retry later
irm is not recognized	You ran a PowerShell command in CMD	Switch to CMD install command, or open PowerShell
'&&' is not valid	You ran a CMD command in PowerShell	Switch to PowerShell's irm command
bash is not recognized	Ran Mac/Linux command on Windows	Switch to PowerShell's irm command
Linux installation Killed	Insufficient memory (OOM killer killed process)	Add swap space (see below), Claude Code requires 4GB+ RAM
Error loading shared library	Installer misjudged system libc type, pulled wrong variant	See official musl/glibc troubleshooting
After login 403 Forbidden	Subscription invalid / Account lacks permission	Check subscription status, or confirm Console account has corresponding role
App unavailable in region	Not supported in your region	See Supported Countries

Let's expand on the two most frequent ones.

Pitfall One: command not found: claude (Most Common)

Running claude says command not found—it's not that it wasn't installed, it's that the installed directory hasn't entered the system search path (PATH).

Analogy: PATH is the system's list of house numbers. The program installed is like a house built, but the system will only look at the addresses registered on the "list of house numbers" one by one. The house of claude is built in ~/.local/bin/, this address wasn't registered on the list, so naturally it can't be found.

Fix (macOS default is Zsh):

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

Linux mostly defaults to Bash, just replace ~/.zshrc with ~/.bashrc. After modifying, verify:

claude --version

Seeing the version number means it's fixed. Windows users should add %USERPROFILE%\.local\bin to the user PATH environment variable, and then restart the terminal.

Pitfall Two: Uncovering "Fighting" Multiple Installations

If you first installed with npm and then with the official script, there might be several claude existing simultaneously, versions don't match, behavior is weird. First see how many are on the PATH:

which -a claude

If it lists more than one, keep only the official script one (~/.local/bin/claude), delete the rest:

# Uninstall npm global installation
npm uninstall -g @anthropic-ai/claude-code

# Delete local npm installation of older versions
rm -rf ~/.claude/local

Most of the time, once which -a claude runs, you'll find npm and native each installed one; deleting the npm one and smoothing out PATH instantly brings peace.

💡 One-sentence summary: Check the table for the cause when an error occurs, don't reinstall by reflex; command not found is mostly PATH, weird behavior is mostly multiple installations fighting, which -a claude will reveal it.

---

07 Hands-on: Run the First Time from Scratch

Just installing it doesn't count, actually run it once to confirm the link is clear. This minimal flow does not depend on an existing project; creating an empty directory will do.

First step, create a test directory and enter it, launch Claude Code:

mkdir claude-test && cd claude-test
claude

The first launch will guide you to log in (follow section 04 to complete), after logging in you'll see the welcome interface.

Second step, type /help in the input box to see what commands are available:

/help

Expected: Pops up a list of available commands and feature descriptions. Just typing a / will also pop up auto-completion for all commands.

Third step, let it do something real—issue instructions directly in plain language (no need to memorize command formats):

Write a function in the test.py file that prints hello world

Expected behavior: Claude Code will first present the code to be changed as a diff (difference comparison) for you to see, and only actually write the file after you confirm (select yes). This is its core workflow—give a plan first, wait for your approval, then act, never secretly changing your things.

After confirmation, there's an extra test.py in the directory. Exit:

exit

At this step, you have completely run the full flow of "install → log in → give instruction → it changes file → you confirm". The first time you see it write out code itself, and still stop to wait for your nod, gives a real sense of "this thing can really work"—the first time you run it through, there will be a little excitement.

This image strings the four steps above into a line: from launching claude, logging in, /help to see commands, plain language instructions, to the most critical link—it first shows you the diff, waits for your nod (yes) before writing the file; if you say no, it won't write, and will try another round after adjusting, without secretly changing your things throughout the process.

💡 One-sentence summary: You can run the full flow in a new empty directory—launch claude and log in, /help for commands, plain language instructions, see diff and click yes, this "give plan first then act" is its core rhythm.

---

08 Summary

This article has thoroughly gone through "installing and using it":

• Confirm three things before installing: OS version is sufficient, account is paid tier or Console, choose CLI.
• Identify the official script: Mac/Linux/WSL use curl, Windows distinguish PowerShell (irm) and CMD; npm is the bad policy, never use sudo.
• Verify with claude --version, health check with claude doctor; if login reports organization disabled, check leftover ANTHROPIC_API_KEY.
• Check table for errors first: Command not found check PATH, weird behavior check multiple installations.

You should now be able to independently install Claude Code on your machine, log in, run the first example, and know where to check when encountering common errors.

Next article 03 · How Claude Code Works—lifts the lid to look inside: How did your sentence "write a hello world function" just now turn into a precise file modification? Behind it is a mechanism called the "agentic loop". Once you understand it, you can truly use Claude Code, rather than just knowing how to type commands.

Leave a question: When you asked it to write test.py just now, did it first look at what files were in the directory, or did it write directly? This difference is exactly the entry point of the next article.

---

Installing it only gives you the tool, knowing its "thinking" is the real skill—see you in the next article.

---

Recommended Reading

• Plugins: Bundle Scattered Configurations with One Click
• Plugins Reference: Package Your Configurations into a Shareable Bundle
• Dev Config: Tune Claude's "Work Environment"