GuidesHosting choices

Install and update Pi coding agent on a Linux server

Install Pi (pi.dev) on Linux: the installer, Node 22.19 on Ubuntu 24.04, the enableCompileCache error, where files land, and how pi update works.

November 17, 2026The Everpod team
The short answer

On a Linux server, install Pi as the user who will run it with curl -fsSL https://pi.dev/install.sh | sh, and update it later with pi update. Pi needs Node.js 22.19 or newer. Ubuntu 24.04’s own Node is 18.19, so the installer says “Pi needs Node.js 22.19.0 or newer and npm. Install them now with …? [Y/n]” and, if you answer yes, fetches Node 22 from nodejs.org into your home folder. From cloud-init or any script with no terminal it can’t ask, so it stops instead: install Node 22.19+ first, then run it. Pi itself lands in ~/.pi/agent/, with the pi command linked into ~/.local/bin. The current release is 1.5.2 (November 10, 2026). Once it runs, connect a model.

Three ways to install, and which one updates itself

Pi’s quickstart offers three routes on Linux. Which one you take decides how pi update behaves later, so it is worth choosing once.

RouteCommandWhat you get
Installer (managed)
curl -fsSL https://pi.dev/install.sh | shEvery dependency pinned to the release’s lockfile, all of it under your home folder, no sudo for Pi itself. pi update works.
npm
npm install -g --ignore-scripts @earendil-works/pi-coding-agentThe quickstart notes it “does not pin transitive dependencies.” pi update works only if npm’s global folder is writable by you.
Nix
nix profile add github:earendil-works/pi/stableBuilt from source; update with nix profile upgrade pi, never pi update.

The npm package used to be @mariozechner/pi-coding-agent; that name stopped at 0.73.1, so an old tutorial’s command installs a version from before 1.0. The installer has no option to pick a version: it always installs the latest release.

Node.js: what Pi needs, and what an old one looks like

Pi 1.5.2 declares Node 22.19.0 or newer. Most server images ship something older:

DistributionIts nodejs package
Ubuntu 22.04
12.22
Ubuntu 24.04
18.19
Debian 12
18.20
Ubuntu 26.04
22.22, new enough

The installer checks before it touches anything. An old Node is reported as “error: Pi requires Node.js 22.19.0 or newer. Found …” with the version it found, and then, old or missing, it offers to fix it:

Pi needs Node.js 22.19.0 or newer and npm. Install them now with standalone Node.js? [Y/n]
Copied

What it offers to install with depends on the system: apt if the distribution’s own nodejs is 22.19 or newer (it runs apt-get install -y nodejs npm, through sudo, and warns “This may ask for your sudo password.”), otherwise a standalone Node 22 build downloaded from nodejs.org, checked against its published checksum and unpacked into ~/.local/share/pi-node. That standalone Node needs no sudo and is put on PATH for Pi by Pi’s own launcher; it does not replace the system’s node for anything else. Answer n and it stops with “Install Node.js 22.19.0 or newer and npm, then run this installer again.”

A Node installed some other way that is still older than Pi wants fails when you start Pi, not when you install it. Pi’s launcher begins by importing enableCompileCache from Node, which Node added in 22.8.0, so on Node 20 or 18 the very first line throws:

SyntaxError: The requested module 'node:module' does not provide an export named 'enableCompileCache'
Copied

That is the message in Pi issue #9938, on Node 20.19.4, which its reporter solved by upgrading Node. It means the Node that ran Pi is too old, not that Pi’s install is broken: check node --version and which node, since a server can have one Node from apt and another from nvm or nodejs.org, and the one first on PATH is the one Pi gets.

Installing from cloud-init or a script

Piped from cloud-init, a Dockerfile or ssh host 'curl … | sh', the installer has no terminal to ask on. If Node is missing or too old, it refuses rather than install Node unasked:

No terminal detected; install Node.js 22.19.0 or newer and npm, then run this installer again.
Copied

So the unattended order is Node first, by whatever means the image uses, then the installer. With a good Node present it prints “No terminal detected; continuing without confirmation.” and installs. Run it as the user who will use Pi, not as root: everything lands in the installing user’s home, so an install made as root under cloud-init is in /root and invisible to your login user.

Where everything lands

A managed install of 1.5.2 prints “Installing managed Pi dependencies”, “Verifying managed Pi 1.5.2”, “Activating managed Pi 1.5.2”, “Managed Pi install complete” and “Update Pi later with: pi update”, and leaves:

~/.local/bin/pi                      the command (a link to the launcher)
~/.pi/agent/bin/pi                   the launcher, which runs the active release
~/.pi/agent/install/releases/1.5.2/  Pi and its pinned dependencies
~/.pi/agent/auth.json                keys and sign-ins (mode 600)
~/.pi/agent/sessions/                your conversations
~/.local/share/pi-node/              Node, only if the installer fetched it
Copied

The link goes into the first of ~/.pi/agent/bin, ~/.local/bin, ~/bin, ~/.bin or ~/local/bin that is already on your PATH, and into ~/.pi/agent/bin when none is. In that last case the install ends with:

Pi was installed, but your shell is not using that install yet.
Restart your shell or run:

  export PATH="/home/you/.pi/agent/bin:$PATH"

Then run: pi
Copied

The installer offers to add that line to your shell’s startup file; otherwise log out and back in, or run the line it printed. pi --version confirms which version answers. Setting PI_CODING_AGENT_DIR moves the ~/.pi/agent folder, which also means a service or cron job that sets it differently sees a different install’s settings and sign-ins.

Updating: what pi update does

pi update with nothing after it updates Pi only. It asks pi.dev for the latest release and, on the current one, says so and stops (Pi 1.5.2’s output):

$ pi update
Extensions are skipped. Run pi update --extensions to update extensions.
pi is already up to date (v1.5.2)
Copied

When there is a newer release, a managed install prints “Updating managed pi installation...”, fetches the new release’s lockfile, installs it beside the old one, checks that it starts, switches the launcher over, prunes old releases and ends with “Updated pi from 1.5.1 to 1.5.2” (with your versions). Everything it touches is in your home folder, so it needs no sudo. The other targets, from Pi’s CLI reference:

pi update --extensions   # every installed package, not Pi
pi update <source>       # one installed package
pi update --models       # refresh model catalogs only
pi update --all          # Pi and every package
Copied

Packages are what Pi’s extensions covers; pinned ones stay where they are. --force reinstalls the same version on an npm install, but a managed install refuses it with “Managed pi installations do not support --force; rerun the installer to repair this installation.”, and running the installer again is the repair.

When pi update cannot update

On a machine that should never call home for versions, PI_SKIP_VERSION_CHECK=1 turns off “the pi.dev latest-version request”, per Pi’s environment variables.

Removing it

For a managed install, run the installer again and choose Uninstall Pi: it removes the launcher, the link and ~/.pi/agent/install. For npm, npm uninstall -g @earendil-works/pi-coding-agent. Note that pi remove removes packages, not Pi. As the quickstart says, “None of these methods removes configuration, credentials, sessions, or installed Pi packages from ~/.pi/agent/”, so auth.json stays until you delete it, and a reinstall finds your sign-ins where they were. What Pi does once installed, and where its makers say to run it, is in what Pi is.

Run the Pi coding agent on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.