Docs

Updating

There are two ways to install Based, the ISO and the installer, and one way to update it: apt, through based-update. The edition itself is a package, based-edition-<cell> (based-edition-dev-sway-trixie for Based Poweruser), so a setting the edition changes and a package it gains reach your machine the same way every other update does.

What happens by itself

Three minutes after every boot, plus a random delay of up to 20 minutes, and once a day after that, your machine:

• installs your distro's security fixes, Debian's or Ubuntu's, and nothing else from apt
• updates your Flatpak apps
• checks for firmware, and never installs it

It never restarts, and offline it just tries again next time. A notification lists what it installed and what's waiting for you.

The update you run

Everything else waits for you: a new Based release, the edition, your other packages, Docker and your mise tools. On Poweruser the update icon beside the weather in the bar names what's waiting ("Based 3.1.5 is ready" on hover), and the notification "Pending Based Updates" says the same at login. Any of these runs the update:

• that icon, or the notification
• Update, then Based in the Omarchy menu
• Update Based Linux from your apps
• based-update in a terminal

It runs in a terminal, in Omarchy's order: your packages and the Based release, then your home's defaults in every session that's open (see Your config files), then Flatpak apps and mise tools, then cleanup. Last, it offers a waiting firmware update and a restart if a new kernel or package needs one. Nothing installs firmware or restarts until you say yes. If a step fails, the terminal names it.

mise moves each tool to the newest release your config allows, so node = "22" goes to the newest 22.x and a version you pinned exactly never changes. Tools that update themselves, such as Claude Code installed from its own script, keep doing that.

sudo based-update runs the same update without Omarchy's steps. On Retro, which has no Omarchy, that's the whole update, and the notification says to open Update Based Linux.

On Poweruser, Update, then Config, then Shell puts the bar's ~/.config/omarchy/shell.json back to the default, keeping yours beside it as a .bak.

apt sources and Dev mode

Based's packages come from one file, /etc/apt/sources.list.d/based.sources, whose suite is your base: d13 on Debian 13, u26 on Ubuntu 26.04 (u24 on an older Ubuntu 24.04 machine).

Update, then Channel has one switch, Dev mode. On, it adds the next release's snapshot suite beside yours, d13-dev or u26-dev, and apt takes whichever version is newer. Off, the next update moves Based's own packages, the edition included, back to the release's versions, some older than what you have, so the switch asks first.

cat /etc/apt/sources.list.d/based.sources

When your organization manages the machine

A machine that joined an organization may follow its policy instead: the daily run then installs everything the update you run would, packages, the Based release, Flatpak apps and mise tools, and its notification says what it installed. It still never restarts; the notification says when a restart would finish the update. Accounts has how a machine joins.

The pure editions

Pure Omarchy and SwayOS stay stock. SwayOS installs Debian's security fixes and point releases by itself through Debian's own unattended-upgrades. Pure Omarchy has no automatic update, as upstream, and uses Omarchy's own Update menu. From a terminal both update with:

sudo apt update
sudo apt full-upgrade

A machine installed from Based 3.1.0, 3.1.1 or 3.1.2 has no automatic update at all until it takes one update by hand: the update icon or Update, then Based on the tiling editions, and the two commands above everywhere else. After that it follows this page.

The edition package

The update installs the edition package on a machine that doesn't have it yet, and upgrades it from then on, always in the update you run. Each new version applies the edition's settings. /var/log/based-edition.log says what it did, and an apply that didn't finish is tried again at your next update.

If you remove a package the edition depends on, apt removes the edition package with it, and the update doesn't put it back. The machine keeps the configuration it has until you install based-edition-<cell> again.

Retired editions

Based releases six editions: Based Workstation, Based Poweruser, Pure Sway, Pure Omarchy, Retro Chicago95 and Retro WhiteSur. A machine installed from an edition that's no longer released moves at its next update when one of those keeps its desktop and its base:

An update never swaps your desktop, so the other retired editions stay where they are and keep getting package updates. To move one to a Based edition, reinstall it from a Based Workstation or Based Poweruser ISO.

Running the installer again

The installer, make os/<cell>/install from a clone or sudo ./install.sh from the tarball, puts an edition on a machine. It isn't how Based updates, though running it again on a Based machine re-applies the edition. It doesn't partition, doesn't replace the kernel or the bootloader, doesn't create users and doesn't reset the hostname or locale. Install a Based edition is the reference.