How to install Claude Code on macOS and Linux: native installer, Homebrew, apt and PATH (and the most common errors)

To install Claude Code on macOS or Linux, open a terminal and run curl -fsSL https://claude.ai/install.sh | bash. The native installer does not need sudo, puts claude in ~/.local/bin and updates itself. If the terminal then says the command does not exist, ~/.local/bin is missing from your PATH. The requirements are macOS 13.0 or newer, or Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+, with 4 GB of RAM and an x64 or ARM64 processor. On a Mac you can also install with Homebrew, and on Linux with apt, dnf or apk.

This post is one of the hands-on guides in the Claude Code guide. The steps follow the official setup docs and install troubleshooting guide. The outputs shown were captured on October 18, 2026 in clean Ubuntu 24.04 and Alpine 3.22 containers (x64), without login, with Claude Code 2.1.302. We did not run anything on a Mac. The macOS and Homebrew commands come from the docs. Windows takes a different path, covered in How to install Claude Code on Windows.

Choose an install method

All four deliver the same native binary. Pick one. Two installs on the same machine can cause version mismatches and unexpected behavior, and which -a claude shows how many are on your PATH.

Check the requirements before installing

The docs require macOS 13.0 or newer, or else Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+. On any of them you need 4 GB of RAM, an x64 or ARM64 processor, a Bash or Zsh shell and an internet connection. On Linux, two lines show the architecture and the C library:

uname -m
ldd --version 2>&1 | head -1

In the test, they returned x86_64 and ldd (Ubuntu GLIBC 2.39-0ubuntu8.9) 2.39. If the second line mentions musl, you are on a distribution like Alpine, which needs extra packages (it has its own section below). On macOS, check the version under Apple menu > About This Mac.

The other check is your account. Claude Code requires a Pro, Max, Team or Enterprise plan or a Console account. The free claude.ai plan does not include access. You can also use it through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry.

Install with the native installer

Open a terminal. On macOS, press Cmd + Space, type Terminal and press Enter. On most Linux distributions, the shortcut is Ctrl + Alt + T. Then run:

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

The command shows no progress while it downloads. In the test, on a clean Ubuntu 24.04 with a regular user and no sudo, it took 24 seconds and printed:

Setting up Claude Code...

Checking installation status...
Installing Claude Code native build latest...
Setting up launcher and shell integration...
⚠ Setup notes:
  ● Native installation exists but ~/.local/bin is not in your PATH. Run:

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

✔ Claude Code successfully installed!

  Version: 2.1.302

  Location: ~/.local/bin/claude


  Next: Run claude --help to get started

⚠ Setup notes:
  ● Native installation exists but ~/.local/bin is not in your PATH. Run:

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


✅ Installation complete!

The installer created ~/.local/bin/claude, a symlink to ~/.local/share/claude/versions/2.1.302. It does not touch the PATH. The Setup notes, which show up twice in the output, only print the command that fixes it. Everything stays in your home folder, so it does not need sudo.

To install the stable channel (usually about a week behind the newest version, skipping versions with serious regressions) or a specific version, pass the argument to bash:

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

On the day of the test, stable installed 2.1.292, while the default channel (latest) was on 2.1.302. The channel you pick at install time becomes the default for automatic updates.

Add ~/.local/bin to your PATH

First check whether the folder is already on your PATH:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

If nothing prints, the folder is missing. Add the line to your shell's config file and reload the file. In Zsh, the default shell on macOS:

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

In Bash, the default on most Linux distributions:

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

In Bash on macOS, use ~/.bash_profile. The macOS Terminal starts Bash as a login shell, and a login shell ignores ~/.bashrc:

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

Then open a new terminal, because a window that was already open keeps the old PATH. A terminal inside an editor inherits the editor's PATH, so quit and reopen the editor too. On the Ubuntu in the test, the default ~/.profile already adds ~/.local/bin to the PATH when the folder exists, and a new login shell found claude with no changes. The installer warns anyway, because the shell where you ran the command does not have the folder yet.

Or install with Homebrew (macOS)

brew install --cask claude-code

The claude-code cask tracks the stable channel. To get each version as soon as it ships, install claude-code@latest. A Homebrew install does not update itself. Run brew upgrade claude-code (or brew upgrade claude-code@latest, depending on the cask) from time to time, or set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 so Claude Code runs the upgrade for you in the background. Homebrew keeps old versions on disk, and brew cleanup frees that space.

If Homebrew answers Error: Cask 'claude-code' is unavailable: No Cask with this name exists, your local index is stale. Run brew update and try again.

Or install with apt, dnf or apk

Anthropic publishes signed repositories for Debian and Ubuntu (apt), Fedora and RHEL (dnf) and Alpine (apk), each with a stable and a latest channel. This path needs sudo (or root, on Alpine), and updates come through the normal system upgrade, not through Claude Code. With apt, start by downloading the key and checking its fingerprint:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
gpg --show-keys /etc/apt/keyrings/claude-code.asc

The fingerprint must be 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. If curl or gpg is missing on the machine, install both first with sudo apt install curl gnupg. Then register the stable repository and install:

echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

In the test, on Ubuntu 24.04, apt installed 2.1.292 at /usr/bin/claude, which is already on the PATH. claude doctor showed Running: package-manager (2.1.292), Package manager: deb and Auto-updates: Managed by package manager. To upgrade later, run sudo apt update && sudo apt upgrade claude-code. To switch to the latest channel, the URL path and the suite name change together, and the line ends in apt/latest latest main.

On Fedora and RHEL, the repository goes into a .repo file:

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

On the first install, dnf asks you to confirm the key fingerprint, which must be 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE. To upgrade, run sudo dnf upgrade claude-code. We did not test dnf. The apk repository commands are in the docs.

On Alpine, install the dependencies first

Alpine and other musl-based distributions ship without bash and curl, and the install command fails with not found until you add them. Claude Code also needs libgcc, libstdc++ and ripgrep at runtime. Install everything with apk:

apk add bash curl libgcc libstdc++ ripgrep

With those packages, the native installer worked on the Alpine 3.22 in the test and installed 2.1.302. One setting is left. Tell Claude Code to use the system ripgrep, in settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

ripgrep lives in Alpine's community repository. If apk cannot find the package, add the community repository for your Alpine version to /etc/apk/repositories, run apk update and repeat the apk add.

Use npm only if you need it

The npm package installs the same native binary, which arrives through a per-platform optional dependency. It needs Node.js 22 or newer, but the installed claude does not use Node to run.

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

Do not use sudo npm install -g. The docs warn that it leads to permission issues and security risks. To upgrade, run npm install -g @anthropic-ai/claude-code@latest. npm update -g respects the version range from the original install and may not reach the newest release.

Verify the install and log in

In a new terminal, run:

claude --version
claude doctor

The first one prints 2.1.302 (Claude Code) (or your version). claude doctor works before login and exited with code 0. Real output, with no account connected:

Claude Code doctor

Running: native (2.1.302)
Commit: 2ef144e6f98c
Platform: linux-x64
Path: /home/dev/.local/share/claude/versions/2.1.302
Config install method: native
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: none recorded
Managed settings (remote): not fetched — no usable credentials for the settings fetch
Organization policy: not fetched: no API key or claude.ai sign-in for the policy lookup (apiKeyHelper keys are not used for it)

Remote Control
Remote Control requires a claude.ai subscription. Run claude auth login to sign in with your claude.ai account.
- Not signed in to claude.ai
...

No installation issues found.

The line that matters is No installation issues found.. The Remote Control and policy lines only say you have not logged in yet. The Path field points to the version folder under ~/.local/share/claude/versions/, not to the symlink in ~/.local/bin.

Then go into the project folder and run claude. Login opens in the browser. Without login, claude -p "hi" exited with code 1 and Not logged in · Please run /login. Over SSH, in a container or on a machine without a browser, the browser opens on another computer and cannot reach the terminal. In that case, the page shows a code after you sign in. Paste that code at the Paste code here if prompted prompt. If pasting into the prompt does not work, use claude auth login, which reads the code from standard input.

On macOS, Claude Code stores the credential in the Keychain. When the Keychain rejects the write (locked in an SSH session, for example), the login goes to a plaintext file, ~/.claude/.credentials.json. claude doctor warns with macOS Keychain is not writable, and security unlock-keychain ~/Library/Keychains/login.keychain-db unlocks the Keychain.

How we use it at Capiva

With Claude Code installed, our next step is the harness. capivaOS installs as a plugin. On a machine without an interactive session, such as CI or a server, the install is two commands (README):

claude plugin marketplace add iB2/capivaOS
claude plugin install capiva@capiva --scope project

The capivaOS hooks need Python 3 available as python3, python or py, and they turn themselves off when none of the three is found. Every claude -p in a pipeline also needs credentials in the environment. Without them, you get the same Not logged in as in the test above.

Troubleshooting checklist

• [ ] zsh: command not found: claude or bash: claude: command not found after installing. ~/.local/bin is not on your PATH, or the terminal predates the change. Follow the PATH section and open a new terminal.
• [ ] zsh: permission denied: /Users/you/.zshrc (or the same with ~/.bashrc). Your user cannot write to the file, and nothing was saved. Check the owner with ls -l ~/.zshrc. If the owner is another user, run sudo chown $(whoami) ~/.zshrc. If it is you, run chmod u+w ~/.zshrc.
• [ ] syntax error near unexpected token '<'. The download returned an HTML page instead of the script. Wait a few minutes and try again, or use Homebrew or apt. If the output mentions App unavailable in region, Claude Code is not available in your country.
• [ ] curl: (22) The requested URL returned error: 403. A proxy or network filter is blocking the download, or your country is not supported. Test access with curl -sI https://downloads.claude.ai/claude-code-releases/latest. The first line must show 200.
• [ ] curl: (23) or curl: (56) Failure writing output to destination. Bash did not receive the whole script. Check the connection and run the command again.
• [ ] Killed or Installation was killed before it could finish (exit code 137). The machine ran out of memory. The install needs about 512 MB free. Close processes or add a swap file, which is common on a remote Linux server with little memory.
• [ ] The install hangs in a Docker container. Run as root from /, the installer scans the whole file system. Set a WORKDIR, such as /tmp, before the RUN.
• [ ] Error loading shared library libstdc++.so.6. The installer downloaded the wrong binary variant, musl on a glibc system. Check with ldd --version 2>&1 | head -1. On Alpine, install libgcc, libstdc++ and ripgrep.
• [ ] Illegal instruction. Either the architecture is wrong (check with uname -m) or the CPU lacks AVX, which happens on many processors from before 2013 and on VMs that do not pass AVX through. If grep -m1 -ow avx /proc/cpuinfo prints nothing, AVX is missing. No other installer fixes it, because they all download the same binary.
• [ ] dyld: Symbol not found, dyld: cannot load or Abort trap: 6 on macOS. Your macOS is older than 13.0. Update the system. Homebrew downloads the same binary and does not fix it.
• [ ] NO_PUBKEY BAA929FF1A7ECACE during apt update. The key download failed. Repeat the key curl and check it with gpg --show-keys.

Frequently asked questions

Read next

• Claude Code is a harness: CLAUDE.md, hooks, MCP and subagents (the main guide)
• How to install Claude Code on Windows, with PowerShell, CMD, WinGet or WSL
• How to write a CLAUDE.md the agent follows, the first file to create after installing
• How to configure hooks in Claude Code
• How to configure MCP in Claude Code
• How to save tokens in Claude Code

Installed it and want Claude Code working with phases and gates from day one? See capivaOS.

Explore more: Free GEO audit