SETUP-DISK(8)

📦 version 3.22.0, in alpine 3.24

💿 setup-disk(8) — the System Manager's Manual, but make it cute ✨

okay so bestie, you're reading the System Manager's Manual page for setup-disk, section 8, and honestly? this one's a whole vibe. it installs Alpine Linux. to a disk. or to a mounted root. let's get into it 💅

🌸 NAME

setup-disk — install Alpine Linux to disk or mounted root 🫶

✨ SYNOPSIS

setup-disk [-hLqrve] [-b DISKDEV] [-B BOOTLOADER] [-k KERNELFLAVOR]
setup-disk [-m MODE] [-o APKOVL] [-R ROOT_SIZE] [-s SWAP_SIZE]
setup-disk [-w FILE] [MOUNTPOINT | DISKDEV...]

like, three whole ways to summon it. pick your fighter 🎀

🦋 DESCRIPTION

setup-disk installs Alpine Linux to a mounted root, or it gets one or more block devices all prepped and ready for a system installation or a data-only installation. lowkey does it all 💖

If you hand it a MOUNTPOINT, setup-disk installs Alpine Linux into that mounted root and sets up bootloader support for you. considerate queen behavior 👑

With disk device arguments, the disks get partitioned and formatted without prompting — no "are you sure", no little confirmation dance, it just goes. and if you pass multiple disks? they get configured as a software RAID array: two disks use RAID1, and more than two disks use RAID5. math! we love her 🧮✨

If you specify no target at all, setup-disk lists the available disks and prompts you for the target disk and the install mode. very "let's figure this out together" of it 🌈

⚠️ bestie, listen to me very carefully: the selected disk devices are erased. gone. wiped. do NOT point this at a disk you like. 😭💀

🎀 MODES

  • sys — do a traditional disk install. the target disk is used for the operating system and normally receives boot, root, and swap storage. the classic. the icon. the main character 👑
  • data — use the target disk for persistent data storage while the operating system keeps running from tmpfs. storage bestie, separate from the OS 🍓
  • crypt — enable encryption and then prompt you again for sys or data mode. yes, it asks twice. it's thorough 💜
  • cryptsys — sys mode, but with encryption enabled. no second prompt, we're being decisive ✨
  • lvm — enable LVM and prompt again for sys or data mode 🦋
  • lvmsys — sys mode with LVM enabled 🔥
  • lvmdata — data mode with LVM enabled 🌸
  • none — exit without installing to disk. the "actually, never mind" option, and honestly? valid 🙈

💅 OPTIONS

  • -b DISKDEV — install the bootloader to DISKDEV when installing to a mounted root. you can specify this bad boy multiple times, stack 'em up 🫶
  • -B BOOTLOADER — use BOOTLOADER instead of the default. supported values: grub, syslinux, zipl, raspberrypi-bootloader, u-boot, limine, none. choose your own adventure ⭐
  • -e — encrypt the disk using LUKS. secret agent mode activated 🔐✨
  • -h — display usage information and exit. the polite escape hatch 🎀
  • -k KERNELFLAVOR — use KERNELFLAVOR instead of the detected kernel flavor 🧚
  • -L — use LVM to manage partitions 🦋
  • -m MODE — use MODE without prompting. valid non-interactive modes are sys, data, and none. (that's the whole non-interactive list, no extras, don't @ me) 👑
  • -o APKOVL — restore the system from the specified apkovl file 💾
  • -q — exit quietly if no disks are found. no drama, no message, just vibes 🍓
  • -r — enable software RAID1 with a single disk. one disk, RAID energy 🌈
  • -R ROOT_SIZE — use ROOT_SIZE MB for the root filesystem instead of maximizing its size 📏
  • -s SWAP_SIZE — use SWAP_SIZE MB for swap instead of autodetecting the swap size. use 0 to disable swap entirely 🚫💤
  • -v — print more information about what is happening. lore drops, but for your disk 💬🔥
  • -w FILE — write the selected install mode to FILE 📝

🌈 ENVIRONMENT

  • BOOTLOADER — select the bootloader. supported values are grub, syslinux, zipl, raspberrypi-bootloader, u-boot, limine, and none. if unset, a default is selected from the architecture and boot environment. and heads up: the -B option takes precedence over this variable 👀
  • BOOTFS, ROOTFS, VARFS — select filesystems for boot, root, and var storage. the default is ext4. supported boot filesystems are ext2, ext3, ext4, btrfs, xfs, and vfat for EFI. root and var support the same list except vfat. sorry vfat, this isn't your department 💅
  • DISKLABEL — select the partition label. supported values are dos and gpt. the default is dos, except EFI installations use gpt. ECKD DASD disks use eckd automatically — it just knows 🧚‍♀️
  • KERNELOPTS — append kernel boot parameters. the default is quiet 🤫
  • DEFAULT_DISK — device name proposed by default in interactive disk selection 🎯
  • ERASE_DISKS — space-separated full device paths that may be processed without the confirmation dialog. key word: full device paths. be sooooo careful with this one 😭
  • USE_EFI — force EFI behavior. this selects gpt partitioning and a vfat boot filesystem ✨

🧚 EXAMPLES

install to /dev/sda in system mode:

setup-disk -m sys /dev/sda

install to /dev/sda without swap:

setup-disk -m sys -s 0 /dev/sda

install to two disks using RAID:

setup-disk -m sys /dev/sda /dev/sdb

install into a mounted root and install the bootloader to /dev/sda:

setup-disk -b /dev/sda /mnt

use Limine as the bootloader:

setup-disk -B limine -m sys /dev/sda

ate. no crumbs. 🔥

⭐ EXIT STATUS

  • 0 — success. we love a happy ending 💖
  • non-zero — an error occurred. it happens to the best of us 😭

🔥 SEE ALSO

lbu(8), setup-alpine(8), setup-bootable(8), setup-lbu(8), setup-apkcache(8), update-kernel(8) — the whole friend group, go say hi 🫶

👑 AUTHORS

Natanael Copa <ncopa@alpinelinux.org> and others 💜

and that's the page!! this was written for Alpine Linux, dated 2026-06-09, under the SETUP-DISK(8) header — mwah, go forth and install responsibly bestie 🎀✨

📦 where this page comes from