How archlinux/archinstall works
Purpose and Entry Points
Archinstall is a Python-based guided and automated Arch Linux installer, also exposed as a library for scripted installation and in-target system management. CLI/module startup is archinstall/__main__.py and archinstall/main.py; argument parsing and script selection are centralized in archinstall/lib/args.py. The default execution mode is the guided installer at archinstall/scripts/guided.py; alternative installation scripts include archinstall/scripts/minimal.py and archinstall/scripts/only_hd.py.
Orchestration and Installation Boundary
The guided flow collects an installation configuration, validates choices through menus, then drives the installer engine. archinstall/lib/global_menu.py coordinates the major selectable domains, while archinstall/lib/configuration.py loads, saves, and interprets declarative configuration and credentials. archinstall/lib/installer.py is the main imperative boundary that applies the plan to the target system. It runs with system-level privileges, changing real disks and the mounted target filesystem rather than serving a remote application.
Interactive TUI and Localization
Terminal interaction is separated into reusable menu infrastructure and domain menus. Core menu abstractions are in archinstall/lib/menu/abstract_menu.py and archinstall/tui/components.py; installation domains expose menus such as archinstall/lib/disk/disk_menu.py and archinstall/lib/network/network_menu.py. Translation lookup is handled by archinstall/lib/translationhandler.py, backed by compiled and source gettext catalogs under archinstall/locales/.
Storage, Filesystems, and Encryption
Disk selection and partitioning form a high-risk subsystem: hardware/device discovery, partition layouts, filesystem creation/mounting, and target preparation are divided across archinstall/lib/disk/device_handler.py, archinstall/lib/disk/filesystem.py, and archinstall/lib/disk/partitioning_menu.py. Encryption and volume-management choices are represented and applied through archinstall/lib/disk/luks.py, archinstall/lib/disk/lvm.py, and archinstall/lib/disk/encryption_menu.py. This layer interfaces with local block devices and Linux storage tooling, including the parted API (typing stub at stubs/parted/__init__.pyi).
Base-System Provisioning and Boot
After storage is prepared and mounted, the installer provisions Arch packages and bootability. Pacman configuration and package operations are encapsulated in archinstall/lib/pacman/config.py and archinstall/lib/pacman/pacman.py; broader package selection is in archinstall/lib/packages/packages.py. Bootloader selection/configuration is isolated in archinstall/lib/bootloader/bootloader_menu.py and archinstall/lib/boot.py. These stages depend on Arch Linux repositories, package mirrors, pacman, and the target system’s firmware/boot environment.
Network, Mirrors, and System Identity
Network connectivity is both an installer prerequisite and a configured target concern. Wireless/network operations live in archinstall/lib/network/network_handler.py and archinstall/lib/network/wifi_handler.py, with wpa_supplicant integration in archinstall/lib/network/wpa_supplicant.py. Mirror selection and mirrorlist handling are separated in archinstall/lib/mirror/mirror_handler.py. Locale, users, authentication, and host/system settings are collected through archinstall/lib/locale/locale_menu.py, archinstall/lib/user/user_menu.py, and archinstall/lib/authentication/authentication_handler.py.
Profiles, Applications, and Extensibility
Profiles layer optional system roles over the base installation. Profile discovery and selection are in archinstall/lib/profile/profiles_handler.py; common role definitions are archinstall/default_profiles/desktop.py, archinstall/default_profiles/server.py, and archinstall/default_profiles/minimal.py. Desktop and server implementations install role-specific packages/services from archinstall/default_profiles/desktops/ and archinstall/default_profiles/servers/. Post-base optional applications are managed by archinstall/lib/applications/application_handler.py. Plugins are a separate extension boundary at archinstall/lib/plugins.py, allowing customization without modifying the principal installer flow.
Main entry points: installer.py Installer engine · args.py Arguments & script selection · guided.py Guided installer · global_menu.py Installation plan menu
Components 22
Entry & Scripts
- CLI / module startup
archinstall/__main__.py - Arguments & script selection
archinstall/lib/args.py - Guided installer
archinstall/scripts/guided.py - Alternative install scripts · Minimal and disk-only execution modes.
archinstall/scripts/minimal.py
Planning & TUI
- Installation plan menu · Coordinates the major installation choices.
archinstall/lib/global_menu.py - Configuration & credentials
archinstall/lib/configuration.py - Reusable TUI menus
archinstall/lib/menu/abstract_menu.py - Translations
archinstall/lib/translationhandler.py - Domain selection menus · Disk, network, locale, user, and encryption choices.
archinstall/lib/disk/disk_menu.py
Storage Preparation
- Devices & partition layouts
archinstall/lib/disk/device_handler.py - Filesystem & target mounts
archinstall/lib/disk/filesystem.py - LUKS / LVM
archinstall/lib/disk/luks.py - Block devices & Linux tooling
Target Provisioning
- Installer engine · Applies the plan to real disks and the mounted target.
archinstall/lib/installer.py - Network connectivity · Includes Wi-Fi and wpa_supplicant integration.
archinstall/lib/network/network_handler.py - Mirror selection
archinstall/lib/mirror/mirror_handler.py - Pacman provisioning
archinstall/lib/pacman/pacman.py - Boot configuration
archinstall/lib/boot.py - Locale, users & authentication
archinstall/lib/user/user_menu.py - Arch repositories
Roles & Extensions
- Profiles & applications · Selects default desktop, server, or minimal roles and optional apps.
archinstall/lib/profile/profiles_handler.py - Plugin extensions
archinstall/lib/plugins.py
Connections 23
- CLI / module startup → Arguments & script selection: parses invocation
- Arguments & script selection → Guided installer: selects default
- Arguments & script selection → Alternative install scripts: selects mode
- Guided installer → Installation plan menu: collects plan
- Installation plan menu → Configuration & credentials: builds and validates
- Installation plan menu → Domain selection menus: uses
- Domain selection menus → Reusable TUI menus: renders through
- Reusable TUI menus → Translations: localizes text
- Configuration & credentials → Installer engine: installation plan
- Guided installer → Installer engine: drives
- Installer engine → Devices & partition layouts: prepares storage
- Devices & partition layouts → LUKS / LVM: applies layout choices
- LUKS / LVM → Filesystem & target mounts: exposes volumes
- Filesystem & target mounts → Block devices & Linux tooling: partitions and mounts
- Installer engine → Network connectivity: ensures connectivity
- Network connectivity → Mirror selection: enables access
- Installer engine → Pacman provisioning: installs base system
- Mirror selection → Pacman provisioning: configures sources
- Pacman provisioning → Arch repositories: fetches packages
- Installer engine → Boot configuration: makes target bootable
- Installer engine → Locale, users & authentication: configures target
- Installer engine → Profiles & applications: installs selected roles
- Plugin extensions → Installer engine: customizes flow