How do I update Headroom?

It updates itself. On macOS, Windows and the Linux AppImage, Headroom installs each update in the background and switches to it once your coding tools have been idle for about an hour. To update now, click Restart to update or Check for updates in Settings. The Linux .deb needs your password, so click Check for updates there. Updating the app also updates the Headroom engine it runs.

For AI agents: this site's index is at /llms.txt, and each docs, guide and blog page comes as Markdown at its URL plus .md.

How to update Headroom

Q: How do I update the Headroom CLI?

Run headroom update, which detects a pip, pipx or uv install and upgrades it in place, then restart any running headroom proxy or headroom wrap session. Older versions without that command update with pip install -U headroom-ai.

The desktop app finds, downloads and installs new versions on its own. Only the Linux .deb needs a click.

How automatic updates work

On macOS and the Linux AppImage, Headroom downloads and installs new versions in the background without a dialog. When one is ready, Settings shows Restart to update next to the app version. Click it, or let Headroom restart itself after about an hour with no requests from your coding tools and its window closed, so it never interrupts a session. It comes back in the menu bar or system tray without opening its window. Until then the running version keeps working.

On Windows, Headroom installs the update at that same idle moment, with no window and no administrator prompt. To install it sooner, click Check for updates in Settings. Running a newer installer over the old one also works and keeps your settings and savings history.

macOS

If Settings says Headroom cannot update itself because it is running from a read-only folder, you opened it straight from the disk image. Drag Headroom to your Applications folder, open it from there, then click Check for updates.

If you installed with brew install --cask headroom, the app still updates itself. The cask is marked as self-updating, so brew upgrade skips it unless you run brew upgrade --greedy. Both routes end in the same place.

Linux .deb

A .deb update needs your password, so Headroom waits for you. Open Headroom from the system tray, go to Settings, and click Check for updates. If you have not updated for five days, Headroom sends a notification and shows the update next time you open it.

You can also download the newest .deb or AppImage and install it over the old one. Your settings and savings history are kept.

Check which version you run

Open Settings. The Tools status card shows Headroom app followed by the version number, and a beta channel label if you receive pre-release builds. The changelog lists what each version changed.

The Headroom engine and add-ons

The desktop app runs its own copy of the Headroom compression engine and updates it together with the app, so there is nothing separate to upgrade. Add-ons you turned on in the Add-ons screen are also kept up to date by the app.

Updating the open-source CLI

A Headroom CLI you installed yourself is separate from the desktop app and does not update automatically; the proxy prints a notice when a new release is out. Update it with:

headroom update

It detects whether you installed with pip, pipx or uv and upgrades in place. On an older version without that command, run pip install -U headroom-ai in the same Python environment you installed it into.

Restart any running headroom proxy or headroom wrap session afterward so the new version is loaded. If headroom is not found after installing or updating, the pip scripts directory is not on your PATH.

Install Headroom for your operating system.

Download for macOS