Claude Code on Linux: install on Ubuntu, sign in, update, fix errors

What it needs

Anthropic’s setup page lists, for Linux, Ubuntu 20.04 or later, Debian 10 or later and Alpine 3.19 or later, on an x64 or ARM64 processor with at least 4 GB of memory and an internet connection. It also publishes package repositories for Fedora and RHEL. Installing takes “roughly 512 MB of free memory”, which matters on the smallest cloud servers.

Install it

The route Anthropic recommends is its own installer, which needs no Node and no root:

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

The docs warn that it “shows no progress while it downloads”. On an Ubuntu 24.04 cloud server on October 11, 2026, in a home folder with Ubuntu’s stock shell files, it finished in about ten seconds and ended with this:

⚠ 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.296

  Location: ~/.local/bin/claude

What it left on disk there was one 257 MB executable at ~/.local/share/claude/versions/2.1.296, with ~/.local/bin/claude as a symlink to it, plus ~/.claude/ and ~/.claude.json for settings and state. 2.1.296 was the newest release that day, published October 9.

From apt instead

Anthropic also publishes a signed apt repository, which suits a machine where every package should arrive through the system’s own updates:

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
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

Before trusting the key, gpg --show-keys /etc/apt/keyrings/claude-code.asc should print the fingerprint 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. The difference from the installer is in the docs’ own words: “Package manager installations do not auto-update through Claude Code; updates arrive through your normal system upgrade workflow.” The stable repository serves a version about a week old; swap both stable words for latest to get every release as it ships.

From npm

npm install -g @anthropic-ai/claude-code installs the same native binary. The package asks for Node.js 22 or later, and the docs are blunt about one thing: “Do NOT use sudo npm install -g”. If npm’s global folder needs root on your machine, use the installer above.

“claude: command not found” straight after installing

This is the note in the installer’s output. Anthropic’s install troubleshooting page says the installer reports the missing PATH entry and “prints the fix with that note but doesn’t change PATH itself”. On the server above, ~/.bashrc and ~/.profile were byte for byte what Ubuntu ships after the install.

On Ubuntu there is a second way out, because the stock ~/.profile adds ~/.local/bin to PATH when the folder exists, and the installer has just created it. On that server a login shell found claude and a plain non-login shell did not:

$ bash -lc 'command -v claude'
/home/you/.local/bin/claude
$ bash -c 'command -v claude'
$

So either log out and back in, or run the line the installer printed, which also covers terminals that are not login shells:

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

Neither helps a command sent as ssh server 'claude …', a cron job or a systemd service, which read neither file as a login does. Give those the full path, ~/.local/bin/claude. The same trap, with the three shells explained, is in the Codex guide for Linux servers, and scheduling Claude Code has a crontab line that uses it.

Sign in on a machine with no browser

Run claude and choose to sign in, or run claude auth login. It tries to open a browser, and where there is none it prints the way round. These are the three lines claude auth login printed on that server:

Opening browser to sign in…
If the browser didn't open, visit: https://claude.com/cai/oauth/authorize?…
Paste code here if prompted >

Open the link on your laptop or phone and sign in to the Claude account this machine should use. Because the browser cannot reach the server’s callback address, it shows a login code instead of redirecting; paste that at the prompt. Anthropic’s docs say this is the normal path “in WSL2, SSH sessions, and containers”, and that the terminal then shows “Login successful”. Two details help over SSH: pressing c copies the link when it wraps across lines and cannot be clicked, and if pasting into the full-screen prompt does nothing, claude auth login “reads the pasted code from standard input”.

To check what the machine is signed in as, without starting a session:

$ claude auth status
{
  "loggedIn": false,
  "authMethod": "none",
  …

That is the signed-out answer; --text prints it for a person. Signed out, a scripted run fails with Not logged in · Please run /login. On Linux the sign-in is stored in ~/.claude/.credentials.json, readable only by your user. It holds your live sign-in, so treat it like a password: it does not belong in a repository or in a backup you share.

claude auth login --console signs in to the Anthropic Console instead, for API billing in place of a subscription. Which Claude plans include Claude Code covers the plans, and using your plan on a server covers what Anthropic’s terms allow there.

An ordinary sign-in can expire, with a warning three days ahead: Your login expires in 3 days · run /login to renew. For runs with nobody present, Anthropic offers a one-year token from claude setup-token. It opens the same browser sign-in, so run it on a machine where that works and set what it prints as CLAUDE_CODE_OAUTH_TOKEN on the server.

Updates: automatic, a week behind, or held

With the installer, “Native installations automatically update in the background”: Claude Code checks at startup and while running, and the new version takes effect the next time you start it. claude update does it on demand. On the server above it printed Claude Code is up to date (2.1.296).

There are two release channels. latest, the default, gets every release as it ships. stable serves “a version that is typically about one week old, skipping releases with major regressions”. You choose at install time, and “The channel you choose at install time becomes your default for auto-updates.”

curl -fsSL https://claude.ai/install.sh | bash -s stable    # the stable channel
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89    # one exact version

On October 11, 2026 the stable install gave 2.1.287, published October 1, while latest was 2.1.296. An installed copy changes channel with "autoUpdatesChannel": "stable" in ~/.claude/settings.json or through /config.

Installing an exact version does not hold it. On that server, claude install 2.1.290 switched to 2.1.290, and the next claude update printed Successfully updated from 2.1.290 to version 2.1.296. To hold a version, switch updating off as well, in the env block of ~/.claude/settings.json or in the environment:

• DISABLE_AUTOUPDATER=1 stops the background check only. The docs: it “only stops the background check; claude update and claude install still work.”
• DISABLE_UPDATES=1 blocks every path. With it set, claude update answered: Updates are disabled by your administrator. Contact your IT team to get the latest version.

A minimumVersion setting also exists, and it is a floor, not a pin: updates refuse to go below it. The installer keeps the two newest versions on disk and deletes older ones itself.

Check an install with claude doctor

claude doctor prints read-only diagnostics without starting a session, so it works before you have signed in and when claude will not start. From the same server:

$ ~/.local/bin/claude doctor
Claude Code doctor

Running: native (2.1.296)
Platform: linux-x64
Path: /home/you/.local/share/claude/versions/2.1.296
Config install method: native
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: none recorded
…
1 warning found
- Native installation exists but ~/.local/bin is not in your PATH

The lines worth reading are the install method, the channel, whether auto-updates are on (with DISABLE_AUTOUPDATER set it reads disabled (set by env: DISABLE_AUTOUPDATER)), the result of the last update attempt, and any warning at the end.

Errors on Linux

Each of these is on Anthropic’s troubleshooting page with its cause.

• Killed, or Installation was killed before it could finish (exit code 137). The machine ran out of memory during the install. Free some, use a larger server, or add swap and run the installer again: sudo fallocate -l 2G /swapfile, sudo chmod 600 /swapfile, sudo mkswap /swapfile, sudo swapon /swapfile.
• Illegal instruction. If uname -m matches the binary, the processor lacks AVX, which the docs put at “roughly pre-2013 Intel and AMD processors, and virtual machines where the hypervisor does not pass AVX through to the guest”. grep -m1 -ow avx /proc/cpuinfo prints nothing on such a machine, and the page says: “There is no native-binary workaround”. It is a reason to check a cheap or unusual virtual machine before building on it.
• Error loading shared library libstdc++.so.6: No such file or directory. The installer fetched the build for musl on a glibc system, which can happen when musl cross-compilation packages are installed. ldd --version says which C library you have. On a glibc system, remove the install and run it again. On Alpine, which really is musl, the fix is apk add bash curl libgcc libstdc++ ripgrep.
• syntax error near unexpected token '<'. The install address returned a web page instead of the script, usually a proxy or a network block in between. A curl: (22) … 403 at the same step can also mean Claude Code is not offered in your country.
• unable to get local issuer certificate and other TLS errors. A minimal image may lack certificate authorities: sudo apt-get update && sudo apt-get install ca-certificates.
• The install hangs or is killed in a Docker build. Run from /, the installer “scans the entire filesystem”. Put WORKDIR /tmp before the install line.
• Failed to start OAuth callback server. Sign-in fails before any link is printed, so there is no code to paste. Anthropic’s errors page gives the way through: run claude setup-token on a machine where sign-in works and set its token on this one, or use an API key.

The sandbox needs two packages

Claude Code can run the shell commands it chooses inside a sandbox, and it is off by default. On Linux it relies on bubblewrap and socat:

sudo apt-get install bubblewrap socat

On Ubuntu 24.04 and later, bubblewrap also needs an AppArmor profile before it may create the user namespaces the sandbox uses; the profile, and the same fix seen from Codex, are in the Codex guide. One default deserves attention on a server: if the sandbox cannot start, “Claude Code runs commands without sandboxing” unless sandbox.failIfUnavailable is set to true. Working without permission prompts covers how the sandbox and the permission modes fit together.

Keep a session running after you disconnect

An interactive claude ends when the SSH connection that started it closes. Anthropic’s own advice for a remote machine is to “start it inside tmux or screen”:

tmux new -s claude
claude
# detach: Ctrl-b d    reattach later: tmux attach -t claude

Claude Code also has background sessions of its own. claude --bg "investigate the flaky test" starts one and returns, and claude agents lists them. A supervisor process keeps them running after the terminal closes, and they survive the machine sleeping. They stop when it shuts down or restarts, and a session that sits finished and unattended for about an hour has its process stopped, with the conversation kept on disk. Agent view is a research preview. For the wider setup, an always-on machine for a coding agent and the security posture it needs, see Claude Code on a VPS.

Uninstall

For the installer’s copy, remove the launcher and the versions; for apt, remove the package and the repository:

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

# apt
sudo apt remove claude-code
sudo rm /etc/apt/sources.list.d/claude-code.list /etc/apt/keyrings/claude-code.asc

Settings, sign-in and session history live apart, in ~/.claude and ~/.claude.json. Deleting them removes all of it, and the desktop app and editor extensions write to the same folder, so leave them if you only mean to reinstall.