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-installin 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 optionsnoatime,compress=zstd:1. Manual partitioning creates@tmptoo unless/tmphas 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 asoem(password from the installer), add apps, test the hardware, then Seal for Customer (icon on the desktop, also shown after login) orsudo 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 locksoem. At the next startluxos-oem-firstboot.servicedeletesoemand creates new SSH host keys. - Setup assistant (
luxos-setup-assistant, full screen, runs as the LightDM greeterluxos-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 issudo luxos-oem finish(allowed forlightdmonly while sealed); every step is journaled in/var/lib/luxos/oem/journaland can be repeated.luxos-oem statusshows the state. The sudo rule (/etc/sudoers.d/90-luxos-oem) names exactlyluxos-oem statusandluxos-oem finishwithout wildcards;finishrefuses to run when the computer is not sealed. The rule and the polkit Wi-Fi rule forlightdmare removed when the assistant finishes; if the power fails in the middle of that,luxos-oem-firstboot.serviceremoves 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 runcryptsetup reencryptlater.
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
luxhas no password, signs in automatically and may usesudowithout a password (the installer needs administrator rights). This is intended. - The
rootpassword is locked – nobody can sign in asrootwith an empty password. Usesudo(orsudo -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 androotlogins. - 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).