Installing LuxOS

The installer is the package luxos-installer: a bash backend luxos-install (text UI with gum, and unattended mode) and a graphical wizard luxos-install-gui (GTK) on top of it.

  • Start in the live system: the Install LuxOS icon (desktop, Dock, welcome window), or sudo luxos-install in a terminal (text UI).
  • The installation takes about 10 minutes and needs internet: current packages are downloaded; LuxOS packages come from the local repository on the ISO (/opt/luxos-repo).
  • Log: /var/log/luxos-install.log (copied to the installed system).
  • Shared files: /usr/share/luxos/installer/ (packages, install.conf.example, lux.conf, templates/*.list, setup-chroot.sh, layout.sh).

Steps

Graphical wizard: Introduction (language) → Network (only when offline) → Keyboard → Time Zone → Destination (disk) → Account → Maintenance → Software → LuxAI account → Summary → installation.

Text UI (sudo luxos-install): language, internet check, keyboard, time zone (auto-detected from the IP address via ip-api.com - plain HTTP, so only a known time zone is accepted - and confirmed), disk, full name / user name / password / computer name, automatic login, maintenance mode, software templates, LuxAI account, summary.

Languages offered: English (US/UK), Čeština, Slovenčina, Deutsch, Polski, Français, Español, Italiano, Português (Brasil), Nederlands, Magyar, Svenska, Українська, or any other locale. The installer UI switches to the chosen language.

Disk modes (Destination)

Mode GUI name DISK_MODE Notes
Whole disk Erase disk and install LuxOS erase everything on the disk is deleted; optional LUKS2 encryption
Free space Install alongside other systems freespace largest free region (min. 20 GB), GPT + UEFI only, shares the EFI partition (needs ≥ 250 MB free on it); GUI and unattended only
Existing partition Replace an existing partition partition formats only ROOT_PART (min. 20 GB, unmounted), other partitions are kept; UEFI only; swap = zram; optionally keep an existing partition as /home without formatting; optional encryption
Manual Manual partitioning (advanced) layout editor for disks, partitions, LVM and LUKS2
Pre-mounted Advanced: use partitions already mounted at /mnt manual / DISK=manual for custom setups such as dual boot; mount root (and /boot) to /mnt first

Minimum disk size is 20 GB.

Default layout (erase)

  • UEFI: ESP 1 GiB FAT32 mounted at /boot + the rest as Btrfs (LuxOS), boot loader systemd-boot.
  • BIOS: 1 MiB bios_grub + 1 GiB ext4 /boot + Btrfs, boot loader GRUB (hidden menu, GRUB_TIMEOUT=0: hold Shift or press Esc while starting).
  • Btrfs subvolumes @ (/), @home, @log (/var/log), @cache (/var/cache), @tmp (/tmp on disk, not in RAM, nodev,nosuid, emptied at every start – see Temporary files), mount options noatime,compress=zstd:1. Manual partitioning creates @tmp too unless /tmp has its own partition.
  • Encryption: LUKS2 on the Btrfs partition (cryptroot); the password is asked at every start.
  • Swap: zram (no swap partition).
  • Kernel: linux-luxos (LuxOS kernel, see Power and performance).

With a shared ESP mounted at /efi, the kernel is copied to EFI/LuxOS/<id> by /usr/local/sbin/luxos-esp-sync (hook /etc/lux/hooks/99-luxos-esp-sync.hook) and systemd-boot is only installed if none is present; a boot menu with a 3 s timeout is created when other systems exist.

Manual partitioning

GUI: Destination › Manual partitioning. Create, delete and resize partitions (resize only ext4, btrfs, NTFS), encrypt a partition or logical volume (LVM on LUKS and LUKS on LVM), LVM volume groups across disks, mount points (/, /home, /var, /tmp, /opt, /srv, /var/log, custom), file systems btrfs/ext4/xfs/f2fs (vfat for the ESP), swap (partition, LV or just zram), keep an existing ESP, VG/LV or unlocked LUKS volume. Presets: Encrypted LVM (/, /home, swap) and Encrypted LVM with separate /var and /tmp.

Checks: an ESP (vfat, ≥ 300 MB) at /boot or /efi on UEFI; on BIOS a type=bios partition and an unencrypted /boot when / is encrypted; no duplicate mount points; sizes; mismatched encryption of / and /home. Separate /usr or /boot/efi are not supported. The summary lists everything that will be erased and must be confirmed.

At boot one password is enough: volumes under / are unlocked by the initramfs (sd-encrypt + lvm2, rd.luks.name); other volumes use a key file in /etc/cryptsetup-keys.d on the encrypted root. If / is not encrypted, encrypted swap gets a random key each boot and other volumes ask.

Unattended installation

sudo luxos-install --config install.conf --yes
... | sudo luxos-install --config - --yes --progress   # config from stdin (passwords never hit the disk)
luxos-install --check-layout layout.conf             # validate a LAYOUT without changes (no root needed)
sudo luxos-install --scan                            # disks, partitions, LUKS, LVM as JSON (read-only)
sudo luxos-install --probe /dev/sdX                  # free space, ESP, partitions (KEY=value, read-only)

Template: /usr/share/luxos/installer/install.conf.example. Keys (bash variables):

Key Meaning / default
LOCALE e.g. cs_CZ.UTF-8 (default en_US.UTF-8)
XKB_LAYOUT, XKB_VARIANT comma-separated, first is default, max 4 (e.g. cz,us and qwerty,)
XKB_OPTIONS switching, e.g. grp:shifts_toggle (both Shift keys, the default); empty = only by clicking the flag in the top bar. Without it a single non-us layout gets us added (both Shift keys)
TIMEZONE e.g. Europe/Prague (default UTC)
DISK target disk, or manual
DISK_MODE erase (default), freespace, partition, layout, manual
BOOTLOADER auto (systemd-boot on UEFI / GRUB on BIOS) or none (kernel stays in /boot)
ROOT_PART, HOME_PART for DISK_MODE=partition (HOME_PART is kept unformatted; ext4/btrfs/xfs/f2fs, btrfs @home subvolume supported)
ENCRYPT, LUKS_PASS 1 = LUKS2 (requires LUKS_PASS)
USERNAME, FULLNAME, PASSWORD required: DISK, USERNAME, PASSWORD
HOSTNAME_SEL computer name (default luxos)
AUTOLOGIN 1 = log in without a password
CARE_MODE carefree (default) or classic, see care-updates.md
COUNTME 1 (default) = anonymous weekly usage count, 0 = off, see countme.md
TEMPLATES comma-separated: everyday, programming, creative, gaming, security
UI_LANG language of installer output
LUXAI_EMAIL, LUXAI_PASSWORD or LUXAI_ACCOUNT optional LuxAI sign-in (account JSON as in ~/.config/luxai/account.json)
LAYOUT / LAYOUT_FILE manual layout for DISK_MODE=layout
LUKS_PASS_<ID> per-volume LUKS passwords in a layout
OEM 1 = prepare for another person (no personal account, see below); then USERNAME and LUKS_PASS are not needed
OEM_SEAL with OEM=1: 1 (default) = sealed right away; 0 = temporary admin account oem with PASSWORD

LAYOUT syntax

One line per item, kind key=value ...:

disk   dev=/dev/vda table=new|keep
part   id=ID disk=/dev/vda size=1G|rest [type=esp|bios|linux|swap|lvm|luks|boot] [name=TEXT]
use    id=ID dev=/dev/sda2 [resize=100G]
delete dev=/dev/sda3
luks   id=ID on=ID name=MAPPER [keep=1]
vg     id=ID name=VG pvs=ID[,ID] [keep=1]
lv     id=ID vg=ID name=LV size=40G|rest [keep=1]
fs     on=ID mount=/home type=btrfs|ext4|xfs|f2fs|vfat [format=1|0] [label=X] [subvol=@home]
swap   on=ID [format=1|0]

Sizes K/M/G/T (binary), one rest per disk/group. / is always formatted. Example (encrypted LVM, UEFI):

disk dev=/dev/vda table=new
part id=esp  disk=/dev/vda size=1G type=esp
part id=crypt disk=/dev/vda size=rest
luks id=cryptlvm on=crypt name=cryptlvm
vg   id=vg name=luxos pvs=cryptlvm
lv   id=root vg=vg name=root size=40G
lv   id=swap vg=vg name=swap size=4G
lv   id=home vg=vg name=home size=rest
fs   on=esp  mount=/boot type=vfat
fs   on=root mount=/ type=btrfs
fs   on=home mount=/home type=btrfs
swap on=swap

Keyboard layouts

The layout for the chosen language's country is listed first; up to 3 more layouts can be added (US is pre-selected for typing passwords). With more than one layout, pressing both Shift keys together switches by default. Layouts apply to the console, X11, the login screen and all users. They can be changed later in the Keyboard Layouts app (see keyboard.md).

Maintenance mode

"How should LuxOS be maintained?": Carefree (recommended) — automatic background updates (not on metered networks, with Data Saver or on low battery), a kept previous kernel and self-repair; Classic (for IT professionals) — no automatic updates or repairs, only notifications.

Below the two modes: checkbox Include this computer in the anonymous LuxOS usage count (once a week) (default on; once a week only the version, update channel and install age, no ID — see countme.md). The text installer asks the same question after the maintenance mode; the summary shows "Anonymous usage count: on - once a week, no personal data".

Software templates

Optional extra apps on top of the base system ("Choose your software"):

ID Name Apps Approx. extra download
everyday Everyday LibreOffice (with language pack), Thunderbird, Galculator, hunspell dictionary 320 MB
programming Programming Lux Code, Code - OSS, Git, git-lfs, GitHub CLI, base-devel, OpenSSH, Python + pip, Node.js + npm, jq, Meld 370 MB
creative Video & Photo Kdenlive, GIMP, Inkscape, darktable, Audacity, OBS Studio 450 MB
gaming Gaming Steam, GameMode, MangoHud (+ 32-bit drivers matching the GPU; enables [multilib]) 650 MB
security Security & Networking Nmap, Wireshark (user added to group wireshark), tcpdump, mtr, traceroute, bind, whois, netcat, iperf3, Gufw, Lynis, arch-audit, KeePassXC 170 MB

If some template apps fail to install, the installation continues with a warning.

Base system

Always installed (/usr/share/luxos/installer/packages): base, lux-engine, linux-luxos, linux-firmware, sof-firmware, alsa-firmware, CPU microcode, btrfs-progs, dosfstools, e2fsprogs, exfatprogs, ntfs-3g, cryptsetup, plymouth, sudo, nano, man pages, networkmanager, pipewire-jack, noto-fonts, luxos-greeter, luxos-printing, luxos-desktop, thunderbird (the e-mail app, see email.md), luxdrop, luxai, luxos-safe, luxos-sandbox, luxos-care, plus drivers from luxos-hwdetect (see drivers.md) and efibootmgr (UEFI) or grub (BIOS). After the base system the installer adds the Firefox and Thunderbird language packs for the system language (firefox-i18n-<lang> and thunderbird-i18n-<lang>, e.g. cs, pt-br, sv-se; skipped for English or when no pack exists). Firefox then follows the system language on its own. Downloads are retried up to 3 times (fewer parallel downloads on retry); mirrors are ranked first. The fastest mirrors for your country (reflector) are written to /etc/lux/mirrorlist of the new system; the installer also writes /etc/lux/lux.conf (the LuxOS default: online [luxos], [luxos-apps], Arch [core]/[extra]; the Gaming template adds multilib). The installed system has the lux layout from the start (/var/lib/lux, /etc/lux/keyring), no pacman files.

Preparing for another person (OEM)

For shops and IT: install LuxOS without a personal account; the owner sets the computer up at the first start, like on a new Mac. GUI: Prepare for another person (OEM) on the first page; text UI: "Who will use this computer?"; unattended: OEM=1.

  • Seal now (OEM_SEAL=1, default): the installed system starts straight into the setup assistant. Prepare first (OEM_SEAL=0): sign in as oem (password from the installer), add apps, test the hardware, then Seal for Customer (icon on the desktop, also shown after login) or sudo luxos-oem seal [--keep-wifi] [--poweroff].
  • Sealing removes logs (except /var/log/luxos-install.log), the journal, package cache, root's history, DHCP leases and saved Wi-Fi networks (unless --keep-wifi), resets /etc/machine-id, removes SSH host keys and locks oem. At the next start luxos-oem-firstboot.service deletes oem and creates new SSH host keys.
  • Setup assistant (luxos-setup-assistant, full screen, runs as the LightDM greeter luxos-setup): Language → Keyboard → Wi-Fi → Time Zone → Account (name, user name, password with an eye icon, optional photo, computer name) → LuxAI (optional) → Disk Password (only when encrypted) → Updates (Carefree/Classic) → it signs in to the new account and the LuxOS Tour starts. Back on every page; the power button offers Restart / Shut Down.
  • Choices (no passwords) are saved in /var/lib/lightdm/.local/state/luxos-setup/; after a crash or power loss the assistant starts again on the same page. The root part is sudo luxos-oem finish (allowed for lightdm only while sealed); every step is journaled in /var/lib/luxos/oem/journal and can be repeated. luxos-oem status shows the state. The sudo rule (/etc/sudoers.d/90-luxos-oem) names exactly luxos-oem status and luxos-oem finish without wildcards; finish refuses to run when the computer is not sealed. The rule and the polkit Wi-Fi rule for lightdm are removed when the assistant finishes; if the power fails in the middle of that, luxos-oem-firstboot.service removes the leftovers at the next start and only then switches itself off.
  • Encryption: the disk is encrypted with a random temporary key that is also in the initramfs (/etc/cryptsetup-keys.d/cryptroot.key), so the computer starts without a password until the owner chooses one (default: the account password). The assistant adds and verifies the owner's password, rebuilds the initramfs without the key, then removes the temporary key slot. At any moment either the initramfs key or the owner's verified password unlocks the disk. Only "Encrypt LuxOS" (one volume), not LUKS in manual partitioning. The LUKS volume key itself is not changed (whoever prepared the computer could have read it); for full protection run cryptsetup reencrypt later.

LuxAI account

Optional step "Sign in to your LuxAI account now?": Sign in with a password, Sign in with a code from e-mail, Create a new account (name, e-mail, password 12–128 characters, accept terms, 6-digit e-mail code) or Skip. The session is saved for the new user in ~/.config/luxai/account.json and used by LuxAI, Lux Code and LSL IDE. See luxai-account.md.

After installation

"LuxOS is installed — Remove the installation media and restart your computer." On first login the LuxOS Tour starts. Updates afterwards: lux update or Software Update.

Live system security

The live system on the USB stick is made for trying LuxOS and installing it, so it starts without a password:

  • The live user lux has no password, signs in automatically and may use sudo without a password (the installer needs administrator rights). This is intended.
  • The root password is locked – nobody can sign in as root with an empty password. Use sudo (or sudo -i) in the live session. The emergency and rescue shells still open.
  • The SSH server is not switched on. If someone starts it anyway, the live configuration (/etc/ssh/sshd_config.d/10-luxos-live.conf) refuses empty passwords and root logins.
  • The firewall is on; Lux Guard does not run in the live system (see guard.md).

None of this is copied to the installed system: it gets your account with your password, Lux Guard, the firewall and system protection (/usr read-only, see system-protection.md) from the first start.

Installer tests (developers)

packages/luxos-installer/tests/ in the LuxOS source: test-layout.sh (no root), gui-smoke.py (GUI), vm-layout-test.sh (as root in a VM); OEM: test-oem.sh (sealing, finish, LUKS key change with a power loss at every step), test_oem_logic.py, gui-oem.py (GUI, Xvfb).