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.
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.
| Route | Command | What you get |
|---|---|---|
Installer (managed) | curl -fsSL https://pi.dev/install.sh | sh | Every 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-agent | The 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/stable | Built 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:
| Distribution | Its 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]CopiedWhat 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'CopiedThat 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.CopiedSo 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 itCopiedThe 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: piCopiedThe 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)CopiedWhen 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 packageCopiedPackages 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
- An npm install made with sudo. Pi updates an npm install by running
npm install -gfor the new version itself, and only if it can write to where the package lives. A global install under/usr/lib/node_modulesmade with sudo is not writable by you, and Pi says “This installation is managed by a global npm install, but the install path is not writable. Update it yourself with:” and the command, which you can run with sudo yourself; moving to the installer, or to a user-owned npm prefix as global npm installs describes, ends it. After a successful npm update Pi also suggests the installer, since “This npm installation of pi does not pin its dependencies.” - Nix, or any wrapper. “
pi updatecannot update Pi when another package manager provides it”, and an install Pi cannot recognise ends with “error: pi cannot self-update this installation.” SetPI_SELF_UPDATE_COMMAND, orselfUpdateCommandin~/.pi/agent/settings.json, andpi updateruns that command when pi.dev has a newer release, filling in{version}and{packageName}. Model catalogs and packages still update either way.
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.