Installation
UFLinux installs from the same ISO you boot as a live system. The installer writes
packages from the signed media repository, so an offline install works; pass --online
to allow official Alpine mirrors for packages that are not on the media.
Board images for Raspberry Pi, Qualcomm, SpacemiT K1 and virtual machines skip this page entirely — they are written to the whole disk and are already installed. See Device images.
What the installer expects
Section titled “What the installer expects”UFLinux is deliberately conservative about your disk. It does not resize, shrink, or reuse anything, and it will not create your layout for you in “prepared” mode.
The installed root filesystem must be XFS, and /boot must be a separate filesystem:
| Firmware | Root | Boot filesystem |
|---|---|---|
| UEFI | XFS at /mnt |
FAT32 EFI system partition at /mnt/boot |
| Legacy BIOS | XFS at /mnt |
ext4 at /mnt/boot |
| PowerPC | XFS at /mnt |
ext4 at /mnt/boot, plus a PReP partition |
1 GiB is a practical size for /boot; 8 GiB is a practical minimum for the root.
For BIOS layouts, the /boot partition has to be marked bootable: the
LegacyBIOSBootable attribute on GPT, or the active flag on a primary MBR partition
(it must be the only partition carrying that flag).
ARM and RISC-V installations require UEFI in this release. Board-specific U-Boot layouts and Raspberry Pi installation are outside the ISO installer. DASD storage is not supported.
Graphical installer
Section titled “Graphical installer”The installer opens automatically in the live desktop, and Install UFLinux is in the application menu. Choose a language, keyboard, source, disk, account and time zone, then review the proposed changes. Nothing is written until you acknowledge them and select Install. Configure networking first if you want an online install.
Two modes are offered:
- Guided erases the whole selected disk and creates an XFS root plus a 1 GiB boot filesystem. On PowerPC it also creates the PReP partition.
- Prepared uses an existing empty XFS root and a compatible boot partition on the same disk. It does not format or repartition them, though boot files and bootloader sectors may be replaced.
The disk list excludes mounted, in-use and live-media disks. If you close the window during an installation it only hides — reopen Install UFLinux to see progress.
Command-line installer
Section titled “Command-line installer”Prepare and mount the partitions yourself. Formatting commands destroy data, and the CLI installer intentionally never runs them.
doas uflinux-install --target /mnt --user alice --dry-run
# BIOS or PowerPC also need the whole boot disk:doas uflinux-install --target /mnt --user alice --boot-disk /dev/sda --dry-runCheck the devices it prints, then run the same command without --dry-run. You confirm
by typing a phrase containing the root filesystem’s UUID, then set and repeat a password
of at least eight characters for the new user.
Optional flags:
| Flag | Meaning |
|---|---|
--hostname NAME |
Set the machine’s hostname |
--boot-mode uefi|bios|native|auto |
Override firmware detection; bios for x86 legacy BIOS, native for PowerPC |
--online |
Allow official Alpine mirrors for packages missing from the media |
The root must be empty apart from boot and lost+found. Concurrent installations are
rejected with a lock, and --dry-run changes nothing.
What gets written
Section titled “What gets written”UEFI systems get systemd-boot with its kernel and initramfs stored directly on the EFI system partition, so package updates replace the files the firmware actually boots. UFLinux registers itself in the UEFI firmware and also installs its fallback boot path.
The installed system receives:
- a new regular user with password-authenticated
doas, and a locked root account; - the full stable update repository list — the signed UFLinux repository, the matching
Alpine
mainandcommunity, and UFLinux’s apps repository on the architectures it indexes (see Updating); - ReGreet as the greeter, using the adw-gtk3 dark theme, starting the UFLinux desktop directly with no session selector;
- an initramfs containing the graphics drivers that were active during installation, so early graphics need little firmware. Other drivers and the full firmware collection load after the root filesystem mounts.
Live credentials, live autologin and live-only services are not carried over. Wi-Fi secrets are not copied — reconnect in Settings after the first boot.
If an installation fails, do not boot the partial target. Read the reported failure, then clean and reprepare the target before retrying.
If you change the graphics hardware later, the system may fall back to the firmware
framebuffer during early boot. Updating /etc/mkinitfs/features.d/uflinux-graphics.modules
and rebuilding the initramfs restores early loading for the new driver.
Unmount the target filesystems and remove the media before booting the installed system.
Derived from docs/installing.md inUFlinux-project/uflinux3(b4f4817). Report documentation problems inUFlinux-project/docs.