Docs

Installing Based

Debian editions carry two installers on one image. Ubuntu editions carry the graphical one only.

You need at least 15 GB of disk and 1 GB of RAM. An edition that carries more in its image asks for more. The installer checks for a network but does not need one.

The developer editions need 4 GB of RAM. Below that the installer's welcome page warns you, and so does onboarding's at first login, though neither stops you. The number comes from onboarding, which installs the language toolchains at first login. /tmp is a RAM disk sized at half of memory, so 4 GB of RAM gives it about 1.9 GB, and the Rust download alone unpacks to about 1.9 GB. That is why the Rust step unpacks in your home folder on disk instead, and why it wants about 4 GB of free disk before it starts. With less it stops and says how much it needed. The install steps also clear their temporary files when they end, failed or not, so one that fails cannot starve the steps after it. Below 4 GB of RAM, onboarding is not tested.

Getting an image

Each edition's newest image is named in a small file beside it. For Based Poweruser:

curl -s https://downloads.basedlinux.com/based-iso/poweruser/latest/based-poweruser-d13-amd64.iso.json

Its url is the image. Download that, and the .sha256 file of the same name beside it, and check it before you write it to a USB stick:

sha256sum -c based-poweruser-d13-amd64.iso.sha256

Based Workstation is workstation/latest/based-workstation-u26-amd64.iso.json. The other four sit under their edition's name, such as retro-chicago95-trixie/latest/live-image-amd64.hybrid.iso.json. The images are amd64. On an arm64 machine, install Debian first and put Based on top, below.

The graphical installer

Boot the image, let it reach the desktop, and start the installer. It carries the product's name: Install Based Home on Based GNOME, sway, SwayFX, Hyprland, Plasma and the Zorin look, and Install Based Workstation, Install Based Poweruser, Install Based Retro, Install Based WhiteSur, Install Omarchy or Install SwayOS on the others. On GNOME, Plasma, XFCE and the Zorin look it is in the application menu, and on XFCE it is an icon on the desktop too. On the editions with the Omarchy bar, Based sway, SwayFX, Hyprland, Based Poweruser and pure Omarchy, it is a button on the bar. On SwayOS it is a button on sway's prompt bar, and in the Super+D launcher. The live session is a working desktop, so you can look around first.

The pages are Welcome, Location, Keyboard, Partitions, Users, Summary, on every edition. Nothing is written until you pass Summary, which lists what is about to happen first.

On Partitions the default is to erase the disk and lay it out for you, with btrfs as the filesystem. ext4 and xfs are the alternatives. Manual partitioning is there if you want to place things yourself. On btrfs the installer also sets up snapper: a snapshot of the fresh install, then one before every apt run, each listed in a submenu of the boot menu.

There is no disk encryption. Partitions does not offer "Encrypt system", because the image carries nothing that could unlock an encrypted disk at boot.

On Users you give your name, a login name, a password and a hostname. The account you make is an administrator: it goes in sudo, and in docker on the editions that ship Docker. The installer sets no root password, so you administer the machine with sudo. There is no automatic login.

The last page offers to restart, already ticked. Take the install medium out as it does.

A btrfs install ends with a read-only snapshot of the system it just wrote, @factory. On the editions with the Omarchy menu, Setup offers two resets built on it. Reset Computer puts the system back as it was installed and gives every account an empty home, so the next sign-in runs first-run setup again; logs, Docker data and snapshots start over too. Reset System, Keep Files puts only the system back: packages and system settings return to installation, and your home, accounts, network connections and Bluetooth pairings stay. Both keep your password and finish on the next restart. sudo based-system-reset --erase and --keep-files do the same from a terminal.

The text installer

On the Debian editions the boot menu has Debian's own installer as well, so you can install without starting a desktop at all. Pick it at the very first screen, before the live session:

• Graphical install
• Install, the text one
• Install with speech synthesis

Both boot menus have an advanced submenu for expert and rescue modes. On a BIOS machine it is Advanced install options.

Use this path on a machine that will not run the live desktop, or when you want Debian's partitioner rather than Calamares'.

The Zorin look editions, the Ubuntu ones, have no text installer. Ubuntu has no Debian installer, so those images carry Calamares only.

Onto a system you already have

Based also goes onto a Debian 13 you already run, or Ubuntu 26.04 for Based Workstation, with no reinstall: your disk, your accounts and your files stay. The machine has to match the edition: same distro, same release, same arch. Based Workstation is amd64 only; the others come for amd64 and arm64.

The prebuilt installer needs no clone and no toolchain. Each release carries one per edition and arch, named after the edition's cell with dashes:

edition=dev-sway-trixie
arch=$(dpkg --print-architecture)
base=https://downloads.basedlinux.com/based-binaries
version=$(curl -fsSL "$base/latest/VERSION")
curl -fLO "$base/$version/$edition-$arch-install.tar.gz"
curl -fLO "$base/$version/SHA256SUMS"
sha256sum -c --ignore-missing SHA256SUMS
tar -xzf "$edition-$arch-install.tar.gz"
cd "$edition-$arch-install"
sudo ./install.sh

Or from a clone of the Based repo, make os/<cell>/install, where <cell> is the edition's name in the editions table, such as dev/sway/trixie. Install a Based edition is the reference for both.

After that the machine updates like every other Based machine, through apt: see Updating. Your dotfiles follow Your config files, including how to tell Based to leave one alone.

On an Apple Silicon Mac

Based runs on an M-series Mac through Asahi Linux. Get Debian 13 running on the Mac first, then put Based on top with the arm64 installer tarball or make os/<cell>/install, as above. The kernel, the firmware and the boot chain stay Asahi's, and Based installs only the system on top, so Based Workstation, which is amd64 only, can't go there. The installer adds what the Mac needs, such as the speaker stack, and the boot splash and boot menu are themed as on any other machine. macOS stays in the Mac's own startup picker, not in the boot menu.

On macOS

Based itself doesn't run on macOS, but Omarchy's menu, themes and shortcuts do. See Omarchy on a Mac.

After it reboots

The first login runs onboarding, except on the pure editions. See First boot.