.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The install itself takes under a minute on Ubuntu. What eats people's time is picking the wrong method (usually npm, out of habit) and then wondering why the shell can't find claude or why the CLI sits on a stale version for months. I've put Claude Code on a laptop, two VPSes and one container I'm not proud of, and the native installer has been the right call every single time. This guide covers the install routes on a fresh Ubuntu 24.04 VPS, verification, the login flow including the headless case and how updates work.
Requirements for Claude Code on Ubuntu
You need a paid Claude plan (Pro, Max, Team or Enterprise) or a Claude Console account with an API key. There's no free-tier access to Claude Code. On the OS side, Anthropic supports Ubuntu 20.04+ and Debian 10+; everything below was run on Ubuntu 24.04.
Hardware barely matters: 4 GB of RAM and an x64 or ARM64 CPU is the whole list, because the CLI doesn't run a model locally. Inference happens on Anthropic's API, so there's no GPU requirement and no multi-gigabyte model download. You do need a working internet connection the entire time you use it, which is one reason a server install works so well. If you're setting up a box for this anyway, the one-click template on LumaDock's Claude Code VPS hosting page deploys Ubuntu with the CLI preinstalled and skips the install steps below entirely.
Claude Code CLI installation options on Ubuntu
Anthropic ships a native installer, an npm package, signed Linux repositories and Homebrew casks for macOS. On Ubuntu the first three are relevant, and my position after running all of them is simple: use the native installer unless company policy forces you elsewhere. It has zero dependencies and keeps itself updated in the background, and at no point does it ask for sudo.
Native installer (recommended)
One command as your normal user:
curl -fsSL https://claude.ai/install.sh | bashThe script detects your architecture, drops the binary under ~/.local/share/claude/versions/ and symlinks it at ~/.local/bin/claude. Everything stays inside your home directory, which is exactly what makes removal and method-switching painless later. Native installs also auto-update: the CLI checks on startup and periodically while running, downloads the new build in the background and picks it up the next time you start it.
Confirm it worked:
claude --version
claude doctorThe first prints a version on the current 2.1 line followed by "(Claude Code)". claude doctor runs read-only diagnostics covering install health, settings-file validation and the result of the last update attempt. I run it once after every fresh install; it has caught a broken PATH for me faster than any manual poking around.
Fix claude command not found
If bash reports command not found right after a successful install, ~/.local/bin isn't on your PATH yet. Ubuntu's default ~/.profile adds that directory, but only if it existed when your session started, so a fresh install inside the same SSH session trips over this constantly. The fix:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcLogging out and back in works too. For anything beyond PATH (the install script returning HTML, 403s from a proxy, several installs fighting each other), I've collected the fixes in the Claude Code troubleshooting guide, and Anthropic maintains its own installation troubleshooting page with an error-to-fix table.
npm install
The npm route exists and works:
npm install -g @anthropic-ai/claude-codeIt requires Node.js 22 or newer since v2.1.198. On older Node, npm prints an EBADENGINE warning but the install still completes and runs, since the package downloads the same native binary the curl script does and never touches your Node at runtime. Still on Node 20? The walkthrough for upgrading Node.js 20 to 24 LTS on Ubuntu gets you there first. That runtime detail is also why I skip npm here: it adds a package manager between you and a binary that doesn't need one.
Never run this install with sudo. Anthropic warns against it directly, and a root-owned npm global directory is what breaks self-updates later with permission errors. If your npm setup demands sudo for global installs, that's a Node configuration problem worth fixing on its own (nvm, or a user-owned prefix).
apt repository
Anthropic also publishes a signed apt repo, which makes sense when you want claude-code managed alongside the rest of the system's packages. The condensed version, using the stable channel:
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-codeThere's no auto-update on this path; upgrades ride sudo apt upgrade like every other package. That's fine for a fleet with unattended-upgrades configured and wrong for a personal machine in my opinion, because you'll lag behind fixes without noticing.
Log in to Claude Code
Start the CLI inside a real project, since it works against the current directory:
cd ~/projects/my-app
claudeThe first start walks you through OAuth: pick the subscription login, a browser opens, you approve, done. Type /status any time to confirm which account and organization you're signed in as. One gotcha worth knowing up front: an ANTHROPIC_API_KEY exported in your shell, once approved, overrides the subscription login and bills your Console account instead. If you didn't set that variable deliberately, unset ANTHROPIC_API_KEY and restart the shell before logging in.
Login on a headless server
On a VPS there's no browser to open. When /login shows the OAuth screen, press c to copy the login URL, open it in the browser on your laptop or phone, authorize and paste the code it hands back into the server's terminal. The credential is stored on the server afterward, so you only go through this once per machine. I've written up the full server workflow, tmux included, in the guide to running Claude Code on a VPS.
Once you're in, ask it something real ("where is auth handled in this codebase?") and watch it search the project before answering. The complete first session, from codebase questions through the first commit, is covered in how to use Claude Code.
Update Claude Code
Native installs update themselves in the background. To force a check right now:
claude updateA successful run reports the old and new version numbers; if nothing changed, it tells you you're current. Release notes live in the claude-code GitHub repository if you want to see what each version changed before it lands on your machine.
Stable vs latest channel
Two release channels exist. The default, latest, receives every release as it ships. The stable channel runs about a week behind and skips releases with major regressions. Switch through /config (Auto-update channel) or in settings.json:
{
"autoUpdatesChannel": "stable"
}I keep my laptop on latest and servers on stable. A regression landing mid-task on an unattended box is a bad trade for getting features a few days early.
Switch install methods cleanly
Moving from npm to the native installer (by far the most common direction) is a two-step job. Remove the npm copy first so its shim can't shadow the new binary:
npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bashIf claude still resolves strangely afterward, hunt for survivors with which -a claude; a leftover launcher earlier in your PATH wins over the fresh install. claude doctor flags conflicting installations too, and the official setup documentation keeps per-method uninstall commands if you're clearing out apt or Homebrew copies instead.
That combination, native installer plus the stable channel, has survived months of unattended updates on my servers without a single broken morning. The interesting work starts after the install anyway.
