# archlinux/archinstall architecture

> Architecture diagram of the GitHub repository archlinux/archinstall, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/archlinux/archinstall
- Repository: https://github.com/archlinux/archinstall

## Overview

#### 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: [`archinstall/lib/installer.py`](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/installer.py) (Installer engine), [`archinstall/lib/args.py`](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/args.py) (Arguments & script selection), [`archinstall/scripts/guided.py`](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py) (Guided installer), [`archinstall/lib/global_menu.py`](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/global_menu.py) (Installation plan menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry &amp; Scripts"]
  node_startup["CLI / module startup<br/>Python entrypoint<br/>[__main__.py]"]
  node_args["Arguments &amp; script selection<br/>argument parser<br/>[args.py]"]
  node_guided["Guided installer<br/>installation script<br/>[guided.py]"]
  node_alternatives["Alternative install scripts<br/>installation scripts<br/>[minimal.py]"]
end

subgraph group_planning["Planning &amp; TUI"]
  node_global_menu["Installation plan menu<br/>orchestrator<br/>[global_menu.py]"]
  node_configuration["Configuration &amp; credentials<br/>configuration model<br/>[configuration.py]"]
  node_tui["Reusable TUI menus<br/>terminal UI<br/>[abstract_menu.py]"]
  node_translation["Translations<br/>gettext lookup"]
  node_domain_menus["Domain selection menus<br/>interactive menus<br/>[disk_menu.py]"]
end

subgraph group_storage["Storage Preparation"]
  node_storage_discovery["Devices &amp; partition layouts<br/>storage discovery<br/>[device_handler.py]"]
  node_filesystem["Filesystem &amp; target mounts<br/>storage provisioning<br/>[filesystem.py]"]
  node_encryption["LUKS / LVM<br/>storage encryption<br/>[luks.py]"]
  node_block_devices[("Block devices &amp; Linux tooling<br/>local system boundary")]
end

subgraph group_provision["Target Provisioning"]
  node_installer{{"Installer engine<br/>privileged orchestrator<br/>[installer.py]"}}
  node_network["Network connectivity<br/>network handler<br/>[network_handler.py]"]
  node_mirrors["Mirror selection<br/>mirror handler<br/>[mirror_handler.py]"]
  node_pacman["Pacman provisioning<br/>package installer<br/>[pacman.py]"]
  node_boot["Boot configuration<br/>boot provisioner<br/>[boot.py]"]
  node_identity["Locale, users &amp; authentication<br/>system identity<br/>[user_menu.py]"]
  node_arch_repos[("Arch repositories<br/>external package source")]
end

subgraph group_extensions["Roles &amp; Extensions"]
  node_profiles["Profiles &amp; applications<br/>role provisioning"]
  node_plugins["Plugin extensions<br/>extension boundary<br/>[plugins.py]"]
end

node_startup -->|"parses invocation"| node_args
node_args -->|"selects default"| node_guided
node_args -->|"selects mode"| node_alternatives
node_guided -->|"collects plan"| node_global_menu
node_global_menu -->|"builds and validates"| node_configuration
node_global_menu -->|"uses"| node_domain_menus
node_domain_menus -->|"renders through"| node_tui
node_tui -->|"localizes text"| node_translation
node_configuration -->|"installation plan"| node_installer
node_guided -->|"drives"| node_installer
node_installer -->|"prepares storage"| node_storage_discovery
node_storage_discovery -->|"applies layout choices"| node_encryption
node_encryption -->|"exposes volumes"| node_filesystem
node_filesystem -->|"partitions and mounts"| node_block_devices
node_installer -->|"ensures connectivity"| node_network
node_network -->|"enables access"| node_mirrors
node_installer -->|"installs base system"| node_pacman
node_mirrors -->|"configures sources"| node_pacman
node_pacman -->|"fetches packages"| node_arch_repos
node_installer -->|"makes target bootable"| node_boot
node_installer -->|"configures target"| node_identity
node_installer -->|"installs selected roles"| node_profiles
node_plugins -.->|"customizes flow"| node_installer

click node_startup "https://github.com/archlinux/archinstall/blob/master/archinstall/__main__.py"
click node_args "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/args.py"
click node_guided "https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py"
click node_alternatives "https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/minimal.py"
click node_global_menu "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/global_menu.py"
click node_configuration "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/configuration.py"
click node_tui "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/menu/abstract_menu.py"
click node_translation "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/translationhandler.py"
click node_domain_menus "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/disk/disk_menu.py"
click node_installer "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/installer.py"
click node_storage_discovery "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/disk/device_handler.py"
click node_filesystem "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/disk/filesystem.py"
click node_encryption "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/disk/luks.py"
click node_network "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/network/network_handler.py"
click node_mirrors "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/mirror/mirror_handler.py"
click node_pacman "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/pacman/pacman.py"
click node_boot "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/boot.py"
click node_identity "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/user/user_menu.py"
click node_profiles "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/profile/profiles_handler.py"
click node_plugins "https://github.com/archlinux/archinstall/blob/master/archinstall/lib/plugins.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_startup,node_args,node_guided,node_alternatives toneBlue
class node_global_menu,node_configuration,node_tui,node_translation,node_domain_menus toneAmber
class node_storage_discovery,node_filesystem,node_encryption,node_block_devices toneMint
class node_installer,node_network,node_mirrors,node_pacman,node_boot,node_identity,node_arch_repos toneRose
class node_profiles,node_plugins toneIndigo
```

## Components

### Entry & Scripts

- [CLI / module startup](https://github.com/archlinux/archinstall/blob/master/archinstall/__main__.py): Python entrypoint · `archinstall/__main__.py`
- [Arguments & script selection](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/args.py): argument parser · `archinstall/lib/args.py`
- [Guided installer](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py): installation script · `archinstall/scripts/guided.py`
- [Alternative install scripts](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/minimal.py): installation scripts · Minimal and disk-only execution modes. · `archinstall/scripts/minimal.py`

### Planning & TUI

- [Installation plan menu](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/global_menu.py): orchestrator · Coordinates the major installation choices. · `archinstall/lib/global_menu.py`
- [Configuration & credentials](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/configuration.py): configuration model · `archinstall/lib/configuration.py`
- [Reusable TUI menus](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/menu/abstract_menu.py): terminal UI · `archinstall/lib/menu/abstract_menu.py`
- [Translations](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/translationhandler.py): gettext lookup · `archinstall/lib/translationhandler.py`
- [Domain selection menus](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/disk/disk_menu.py): interactive menus · Disk, network, locale, user, and encryption choices. · `archinstall/lib/disk/disk_menu.py`

### Storage Preparation

- [Devices & partition layouts](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/disk/device_handler.py): storage discovery · `archinstall/lib/disk/device_handler.py`
- [Filesystem & target mounts](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/disk/filesystem.py): storage provisioning · `archinstall/lib/disk/filesystem.py`
- [LUKS / LVM](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/disk/luks.py): storage encryption · `archinstall/lib/disk/luks.py`
- **Block devices & Linux tooling**: local system boundary

### Target Provisioning

- [Installer engine](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/installer.py): privileged orchestrator · Applies the plan to real disks and the mounted target. · `archinstall/lib/installer.py`
- [Network connectivity](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/network/network_handler.py): network handler · Includes Wi-Fi and wpa_supplicant integration. · `archinstall/lib/network/network_handler.py`
- [Mirror selection](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/mirror/mirror_handler.py): mirror handler · `archinstall/lib/mirror/mirror_handler.py`
- [Pacman provisioning](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/pacman/pacman.py): package installer · `archinstall/lib/pacman/pacman.py`
- [Boot configuration](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/boot.py): boot provisioner · `archinstall/lib/boot.py`
- [Locale, users & authentication](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/user/user_menu.py): system identity · `archinstall/lib/user/user_menu.py`
- **Arch repositories**: external package source

### Roles & Extensions

- [Profiles & applications](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/profile/profiles_handler.py): role provisioning · Selects default desktop, server, or minimal roles and optional apps. · `archinstall/lib/profile/profiles_handler.py`
- [Plugin extensions](https://github.com/archlinux/archinstall/blob/master/archinstall/lib/plugins.py): extension boundary · `archinstall/lib/plugins.py`

## Connections

- 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
