SU8 Codes
< Back to blog
Official article Updated 6 min read

How to Install Claude Code on macOS and Linux

Install Claude Code on macOS or Linux with one command, verify it, and fix the common installer errors. Tested with 2.1.323.

#claude-code#install
How to Install Claude Code on macOS and Linux

To install Claude Code on macOS or Linux, run the official installer in a terminal:

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

Then open a new terminal and run claude --version. If it prints a version number, the install worked. For what comes next (sign-in, a first edit, daily commands), see the Claude Code tutorial; to compare it with other tools first, see how the main AI coding agents compare.

What was tested: on November 14, 2026, the native installer, claude --version, and claude doctor were run with Claude Code 2.1.323 on macOS and Ubuntu, and the npm install on Ubuntu only. Homebrew, apt/dnf/apk, the PATH fix commands, upgrading, uninstalling, and turning off auto-updates follow the official setup page as of that date and weren't tested.

Requirements

ItemRequirement
macOS13.0 or later
LinuxUbuntu 20.04+, Debian 10+, Alpine 3.19+
RAM4 GB or more
CPUx64 or ARM64
NetworkInternet access, from a country Anthropic supports

Source: official setup page, November 14, 2026.

  • ripgrep usually ships with Claude Code, and Git is optional.
  • On Alpine, install bash and curl first: apk add bash curl.

You also need an account to use it. The docs list Pro, Max, Ultra, Team, Enterprise, or Console accounts; the free claude.ai plan doesn't include Claude Code. Third-party API providers such as Amazon Bedrock are another option; the Claude Code tutorial shows how to point it at a gateway.

Install and verify

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

The installer shows no download progress, so let it finish. It places Claude Code under ~/.local/share/claude/versions/ and puts a launcher at ~/.local/bin/claude.

Open a new terminal window, then:

claude --version
claude doctor

claude doctor is a read-only health check. Results from the two test machines:

macOS 26.5.2 (Apple Silicon)Ubuntu 22.04 (x86_64)
InstallSucceeded, about 34 secondsSucceeded
claude --version2.1.323 (Claude Code)2.1.323 (Claude Code)
claude doctor (excerpt)Running: native (2.1.323), Search: OK (bundled)Platform: linux-x64, Running: native (2.1.323), Auto-updates: enabled
PATH notice from the installerNot shownShown (see below)

Fix "command not found: claude"

A common cause is that ~/.local/bin isn't on your PATH. The installer detects this and prints a setup note:

Native installation exists but ~/.local/bin is not in your PATH.

It also prints the fix, but doesn't apply it. The Ubuntu test showed this note.

Check that the launcher exists:

ls -la ~/.local/bin/claude

If it does, add the folder to PATH. For Zsh (the default shell in the macOS Terminal):

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

For Bash:

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

Run claude --version again to confirm.

Another case: the VS Code extension bundles its own private copy of the CLI and doesn't create ~/.local/bin/claude. To use claude in a terminal, install it separately.

Fix "syntax error near unexpected token" or a 403

Both errors mean the download wasn't the install script. You got a web page or an error status instead.

bash: line 1: syntax error near unexpected token `<'
curl: (22) The requested URL returned error: 403

The first line is verbatim from the Ubuntu 22.04 test; the official page shows it with a straight quote before <.

According to the troubleshooting page:

  • If the response mentions "App unavailable in region," Claude Code isn't available in your country.
  • A bare 403 with no body often has the same cause, but it can also come from a corporate proxy or firewall.
  • Otherwise, try again later.

If you are in a supported country and still get a 403, the page says to check network connectivity first, because the alternative installers reach the same hosts.

Native vs Homebrew vs npm vs package managers

MethodCommandAuto-updatesGood fit
Native (recommended)curl -fsSL https://claude.ai/install.sh | bashYes, in the backgroundMost people
Homebrewbrew install --cask claude-codeNot by default; run brew upgrade claude-codeMacs where brew manages everything
npmnpm install -g @anthropic-ai/claude-code@latestYes, if the npm global directory is writable; otherwise rerun the installMachines that already have Node.js 22+
apt / dnf / apkSee the official setup page (not tested here)No; updates come with system upgradesServers on Debian/Ubuntu, Fedora/RHEL, or Alpine that use signed system packages

Notes from the official setup page:

  • Homebrew: the claude-code cask tracks the stable channel, typically about a week behind. claude-code@latest tracks the latest channel.
  • npm: don't use sudo npm install -g; the docs warn it can cause permission issues and security risks. On Node.js older than 22, npm prints an EBADENGINE warning but still installs. Upgrade by rerunning the install command, not npm update -g. The npm route also produced 2.1.323 in the Ubuntu test.
  • apt, dnf, apk: signed repositories with the same stable/latest channels.

Update or uninstall Claude Code

Native installs update in the background. To update now:

claude update

If you're already on the newest version, it prints Claude Code is up to date (<version>).

Uninstall a native install:

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

For Homebrew, run brew uninstall --cask claude-code.

Windows

This guide wasn't tested on Windows. See the official setup page.

FAQ

Does Claude Code need Node.js?

Node.js isn't in the official system requirements. Only the npm route requires Node.js 22 or later.

How do I sign in after installing?

Run claude in a project folder and follow the browser prompts. If ANTHROPIC_API_KEY is set and you approve it when asked, Claude Code skips the login prompt. The Claude Code tutorial walks through the first prompt and first edit.

How do I turn off auto-updates?

Set "DISABLE_AUTOUPDATER": "1" in the env key of your settings.json. This stops only the background check, so claude update still works. Per the docs, claude doctor then shows the Auto-updates line as disabled; this wasn't tested here.