A custom Arch Linux ISO with a TUI installer for a clean Hyprland desktop environment. Boot from USB, answer a few prompts, and walk away with a fully configured Hyprland desktop — GPU drivers, Bluetooth, printing, firewall, and your dotfiles all handled, online or completely air-gapped.
- jakeb-grant/dotfiles - Personal dotfiles managed with chezmoi. The installer can optionally apply these during installation.
- See the section of the README on configuration files for additional detail. Your dotfiles repo must be managed with chezmoi and you must make sure that all Arch packages you want on your base system are contained in either
archiso/airootfs/root/target-packages.x86_64(for packages contained in the standard repos) orarchiso/airootfs/root/aur-packages.x86_64(for AUR packages).
Boot from USB and the installer launches automatically.
If using Ventoy, boot the ISO in GRUB2 mode:
- Select the ISO in Ventoy
- Press Enter, then select "Boot in grub2 mode"
(Normal mode may not work due to ISO boot configuration)
The TUI installer launches automatically and guides you through:
- Lists all available disks (NVMe, SATA, eMMC, etc.), excluding the USB stick the installer booted from
- Requires double confirmation before wiping
- Hostname: Text input, pre-filled with default (configurable)
- Username: Pre-filled with default (configurable)
- Password: Enter and confirm
- Disk encryption: Optional LUKS encryption (can use same password)
- Timezone: Defaults to
America/Denver - Git config: Pre-filled, editable
- Auto-detects ethernet connection
- If no connection, offers WiFi setup with network selection
Partitions (GPT):
| Partition | Size | Format | Mount |
|---|---|---|---|
| EFI | 512MB | FAT32 | /boot |
| Root | Remaining | BTRFS | / |
BTRFS Subvolumes:
| Subvolume | Mount Point | Purpose |
|---|---|---|
@ |
/ |
Root filesystem |
@home |
/home |
User data |
@snapshots |
/.snapshots |
Snapshot storage |
@var_log |
/var/log |
Log files |
@swap |
/swap |
Swap file (nodatacow) |
Mount options: noatime,compress=zstd,space_cache=v2
Swap File:
- Automatically sized based on RAM (supports hibernation)
- RAM ≤ 2GB: 2x RAM
- RAM 2-16GB: Equal to RAM
- RAM > 16GB: Capped at 16GB
~80 packages providing a base Hyprland desktop, plus AUR packages via yay. The base system boots to Hyprland with a terminal (Ghostty) and sane keybinds; a bar, launcher, and theming are expected to come from your dotfiles (see dotfiles.conf) — customize the package lists to preload whatever your dotfiles need (e.g. quickshell-git is included for the author's setup).
- Locale:
en_US.UTF-8 - Keymap:
us - Shell:
bash - Multilib repository: Enabled (for 32-bit support)
- Git configured with name/email
- GRUB bootloader (UEFI), plus a fallback copy at
EFI/BOOT/BOOTX64.EFIso the disk boots even if the firmware's boot entry is lost (CMOS reset, board swap) - Services enabled: iwd, systemd-resolved, greetd
After reboot:
- greetd/tuigreet login screen appears
- Log in with your username/password
- Hyprland starts automatically
The installer automatically configures:
- Bluetooth (bluez + bluetui)
- Printing (CUPS + drivers)
- Firewall (UFW with user-selected rules)
- GPU drivers (based on detected hardware)
These scripts can also be run manually for reconfiguration:
nvidia-setup # NVIDIA GPUs (dedicated or hybrid)
intel-setup # Intel GPUs (standalone only)
amd-setup # AMD GPUs (standalone only)Which script to use:
| Your Hardware | Script |
|---|---|
| Intel iGPU + NVIDIA dGPU | nvidia-setup |
| AMD APU + NVIDIA dGPU | nvidia-setup |
| Standalone NVIDIA | nvidia-setup |
| Standalone AMD (RX series, APU) | amd-setup |
| Standalone Intel | intel-setup |
- Auto-detects GPU generation (selects correct driver package)
- Detects hybrid graphics (Intel/AMD + NVIDIA)
- Configures early KMS modules in mkinitcpio
- For hybrid: installs
prime-runwrapper for GPU offloading - Adds Hyprland environment variables
- Auto-enables multilib if needed
After nvidia-setup on hybrid graphics:
# Apps run on iGPU by default (power saving)
# Use prime-run to run on NVIDIA dGPU:
prime-run steam
prime-run glxinfo | grep "OpenGL renderer"- Installs Mesa, Vulkan, and VA-API drivers
- Detects if NVIDIA is present and warns about hybrid
- Adds Hyprland environment variables
- Auto-enables multilib if needed
ROCm is not installed by default due to its large size (~500MB+). If you need GPU compute capabilities (OpenCL, machine learning with PyTorch/TensorFlow, Blender GPU rendering), run amd-setup manually after installation:
amd-setup # Will prompt to install ROCm packagesThis requires network access as ROCm packages are not included in the offline ISO.
bluetooth-setup # Bluetooth + Bluetui TUI
printer-setup # CUPS + drivers
firewall-setup # UFW with interactive rules
dotfiles-setup # Clone your dotfiles repoTwo ISO variants are built automatically:
| Variant | Size | Internet Required | Use Case |
|---|---|---|---|
| Online | ~1.2 GB | Yes (during install) | Fast build, always latest packages |
| Offline | ~5-6 GB | No | Air-gapped installs, unreliable network |
- Smaller download
- Packages downloaded during installation
- Always gets latest package versions
- Requires stable internet connection
- All packages pre-built and embedded
- No network required for full installation (including GPU drivers)
- Includes all GPU drivers (NVIDIA, Intel, AMD) - correct ones installed based on detected hardware
- Includes printer drivers, firewall, and Bluetooth packages
- Includes pre-loaded dotfiles (optional)
- Network only needed for: custom dotfiles from a different repo, or AMD ROCm compute packages
Push to main or claude/* branches to trigger a build. Both online and offline ISOs are built in parallel. Download from workflow artifacts.
Manual trigger with options:
- Go to Actions → "Build Arch Linux ISO"
- Click "Run workflow"
- Optionally specify:
- Custom ISO name
- Dotfiles repo URL (for offline ISO)
Note: For security, builds only run on pushes and same-repo PRs. Fork PRs are blocked.
# Install dependencies
sudo pacman -S archiso
# Build (creates online variant)
cd archiso
sudo mkarchiso -v -w /tmp/archiso-work -o /tmp/archiso-out .For offline builds with pre-loaded packages, use the GitHub Actions workflow.
DEFAULT_USERNAME="jacob"
DEFAULT_HOSTNAME="archlinux"
GIT_USER_NAME="jacob"
GIT_USER_EMAIL="86214494+jakeb-grant@users.noreply.github.com"
DEFAULT_TIMEZONE="America/Denver"
DEFAULT_LOCALE="en_US.UTF-8"
DEFAULT_KEYMAP="us"
DEFAULT_FONT="ter-116n"
DEFAULT_SHELL="/bin/bash"These are only pre-filled defaults for the installer prompts—every one can be changed at install time. Forking this repo? Swap in your own values here (the username/name/email above are the author's) and point dotfiles.conf below at your own dotfiles repo.
# Dotfiles repository for ISO builds and dotfiles-setup
DOTFILES_REPO=https://github.com/jakeb-grant/dotfilesThe single source of truth for your dotfiles repo:
- Offline ISO builds: the repo is pre-cloned to
/opt/dotfileson the ISO. The installer detects it and offers to apply it automatically—no network required. - Installer prompt: the remote-repo prompt comes pre-filled with this value (editable).
- Installed system: the file lands at
/etc/dotfiles.conf, wheredotfiles-setupuses it as the default repo when run without an argument.
Leave empty to skip pre-loading dotfiles. Users can still enter a repo URL during installation if network is available.
Packages installed on the target system (the full Hyprland desktop). This is the single source of truth for target packages—the installer reads from this location.
AUR packages installed via yay on the target system. Comments (lines starting with #) and blank lines are ignored.
Packages included in the offline repository but not auto-installed. These are installed on-demand by the setup scripts:
| Category | Packages | Used By |
|---|---|---|
| NVIDIA | nvidia-open-dkms, nvidia-utils, egl-wayland, etc. |
nvidia-setup |
| Intel | mesa, vulkan-intel, intel-media-driver, etc. |
intel-setup |
| AMD | vulkan-radeon, vulkan-tools, etc. |
amd-setup |
| Firewall | ufw |
firewall-setup |
| Printing | cups, ghostscript, gutenprint, etc. |
printer-setup |
This architecture allows the offline ISO to support any hardware configuration without installing unnecessary drivers. The correct packages are installed based on detected hardware during the setup phase.
Packages included in the live environment (for installation/rescue).
archiso/
├── profiledef.sh # ISO profile configuration
├── packages.x86_64 # Live ISO packages
├── pacman.conf # Pacman config (multilib enabled)
├── airootfs/
│ ├── etc/
│ │ ├── dotfiles.conf # Dotfiles repo (offline builds + dotfiles-setup default)
│ │ ├── pacman.conf # Target system pacman config
│ │ ├── pacman.d/
│ │ │ ├── mirrorlist
│ │ │ └── offline-pacman.conf # Offline mode pacman config
│ │ └── skel/.config/hypr/
│ │ └── hyprland.conf # Default Hyprland config
│ ├── opt/
│ │ ├── offline-repo/ # Pre-built packages (offline ISO only)
│ │ └── dotfiles/ # Pre-cloned dotfiles (offline ISO only)
│ ├── root/
│ │ ├── install.conf # Installer defaults
│ │ ├── target-packages.x86_64 # Target system packages (always installed)
│ │ ├── aur-packages.x86_64 # AUR packages (always installed)
│ │ ├── setup-packages.x86_64 # Setup script packages (on-demand)
│ │ └── setup-aur-packages.x86_64 # Setup AUR packages (on-demand)
│ └── usr/local/bin/
│ ├── hyprland-install # Main TUI installer
│ ├── nvidia-setup # NVIDIA driver setup (hybrid support)
│ ├── intel-setup # Intel driver setup
│ ├── amd-setup # AMD driver setup
│ ├── bluetooth-setup # Bluetooth setup
│ ├── printer-setup # CUPS setup
│ ├── firewall-setup # UFW setup
│ └── dotfiles-setup # Dotfiles deployment
├── grub/ # GRUB (UEFI) config
├── syslinux/ # Syslinux (BIOS) config
└── efiboot/ # systemd-boot entries
Tag a commit to create a GitHub release with the ISO:
git tag v1.0.0
git push origin v1.0.0