ARCHINSTALL(1)

NAME
archinstall - archinstall Documentation
archinstall is library which can be used to install Arch Linux.
The library comes packaged with different pre-configured installers, such as the default Guided installation installer.
A demo of the Guided installation installer can be seen here: https://www.youtube.com/watch?v=9Xt7X_Iqg6E.

Some of the features of Archinstall are:

•   No external dependencies or installation requirements. Runs without any external requirements or installation processes.

•   Context friendly. The library always executes calls in sequential order to ensure installation-steps don't overlap or execute in the wrong order. It also supports (and uses) context wrappers to ensure cleanup and final tasks such as mkinitcpio are called when needed.

•   Full transparency Logs and insights can be found at /var/log/archinstall both in the live ISO and the installed system.

•   Accessibility friendly Archinstall works with espeakup and other accessibility tools thanks to the use of a TUI.

GUIDED INSTALLATION
This is the default script the Arch Linux Archinstall package.
It will guide you through a very basic installation of Arch Linux.

NOTE: There are other scripts and they can be invoked by executing archinstall <script> (without .py). To see a complete list of scripts, see the source code directory examples/

The installer has three pre-requisites:

•   The latest version of Arch Linux ISO

•   A physical or virtual machine to install on

•   A working internet connection prior to running archinstall

    NOTE: A basic understanding of machines, ISO-files and command line arguments are needed. Please read the official Arch Linux Wiki to learn more about your future operating system.

    WARNING: The installer will not configure WiFi before the installation begins. You need to read up on Arch Linux networking before you continue.

  Running the guided installation

To start the installer, run the following in the latest Arch Linux ISO:

    archinstall --script guided
The --script guided argument is optional as it's the default behavior.
But this will use our most guided installation and if you skip all the option steps it will install a minimal Arch Linux experience.

  Installing directly from a configuration file
The guided installation also supports installing with pre-configured answers to all the guided steps.
This can be a quick and convenient way to re-run one or several installations.
After each successful installation a pre-configured configuration will be found at /var/log/archinstall both on the live media and the installed system.

There are three different configuration files, all of which are optional.

•   --config that deals with the general configuration of language and which profiles to use.

•   --creds which takes any superuser, user or root account data.

•   --disk_layouts for defining the desired partition strategy on the selected "harddrives" in --config.

    NOTE: You can always get the latest options with archinstall --dry-run, but edit the following json according to your needs. Save the configuration as a .json file. Archinstall can source it via a local or remote path (URL)

        {
            "audio": "pipewire",
            "bootloader": "systemd-bootctl",
            "custom-commands": [
                "cd /home/devel; git clone https://aur.archlinux.org/paru.git",
                "chown -R devel:devel /home/devel/paru",
                "usermod -aG docker devel"
            ],
            "filesystem": "btrfs",
            "gfx_driver": "VMware / VirtualBox (open-source)",
            "harddrives": [
                "/dev/nvme0n1"
            ],
            "swap": true,
            "hostname": "development-box",
            "kernels": [
                "linux"
            ],
            "keyboard-language": "us",
            "mirror-region": "Worldwide",
            "nic": {
                "type": "NM"
            },
            "ntp": true,
            "packages": ["docker", "git", "wget", "zsh"],
            "profile": "gnome",
            "services": ["docker"],
            "sys-encoding": "utf-8",
            "sys-language": "en_US",
            "timezone": "US/Eastern",
        }

    To use it, assuming you put it on https://domain.lan/config.json:

        archinstall --config https://domain.lan/config.json

  Options for --config

(To see which keys are required, scroll to the right in the above table.)
Key | Values | Description | Required
audio | pipewire/pulseaudio | Audioserver to be installed | No
bootloader | systemd-bootctl/grub-install | Bootloader to be installed (grub being mandatory on BIOS machines) | Yes
custom-commands | [ <command1>, <command2>, ...] | Custom commands to be run post install | No
gfx_driver | "VMware / VirtualBox (open-source)" "Nvidia" "Intel (open-source)" "AMD / ATI (open-source)" "All open-source (default)" | Graphics Drivers to install | No
harddrives | [ <path of device>, <path of second device>, ... } | Multiple paths to block devices to be formatted | No[1]
hostname | any | Hostname of machine after installation. Default will be archinstall | No
kernels | [ "kernel1", "kernel2"] | List of kernels to install eg: linux, linux-lts, linux-zen etc | At least 1
keyboard-layout | Any valid layout given by localectl list-keymaps | eg: us, de or de-latin1 etc. Defaults to us | No
mirror-region | {"<Region Name>": { "Mirror URL": True/False}, ..} "Worldwide" or "Sweden" | Defaults to automatic selection. Either takes a dictionary structure of region and a given set of mirrors. Or just a region and archinstall will source any mirrors for that region automatically | No
nic | { type: <ISO|NM|MANUAL> } { "iface": "eth0"} { "dhcp": <boolean>} { "ip": <ip>} { "gateway": <ip>} { "dns": [<ip>]} | Type must be one of ISO, NM, MANUAL. ISO will copy the configuration on the image, NM configures NetworkManager and MANUAL allows to specify custom configuration Only MANUAL: name of the interface Only MANUAL: If set to true DHCP auto will be setup and all further configs ignored Only MANUAL: Ip address to set, is MANDATORY Only MANUAL: Optional gateway Only MANUAL: Optional DNS servers | No
ntp | <boolean> | Set to true to set-up ntp post install | No
packages | [ "package1", "package2", ..] | List of packages to install post-installation | No
profile | Name of the profile to install | Profiles are present in profiles/, use the name of a profile to install it without the .py extension. | No
services | [ "service1", "service2", ..] | Services to enable post-installation | No
sys-encoding | "utf-8" | Set to change system encoding post-install, ignored if --advanced flag is not passed | No
sys-language | "en_US" | Set to change system language post-install, ignored if --advanced flag is not passed | No
timezone | Timezone to configure in installation | Timezone eg: UTC, Asia/Kolkata etc. Defaults to UTC | No

NOTE: [1] If no entries are found in harddrives, archinstall guided installation will use whatever is mounted currently under /mnt/archinstall.

  Options for --creds
Creds is a separate configuration file to separate normal options from more sensitive data like passwords.
Below is an example of how to set the root password and below that are description of other values that can be set.

    {
        "!root-password" : "SecretSanta2022"
    }
Key | Values | Description | Required
!encryption-password | any | Password to encrypt disk, not encrypted if password not provided | No
!root-password | any | The root account password | No
!users | "!password": "<PASSWORD>", "sudo": false|true} | List of regular user credentials, see configuration for reference | No

NOTE: [1] !users is optional only if !root-password was set. !users will be enforced otherwise and the minimum amount of users with sudo privileges required will be set to 1.

  Options for --disk_layouts

NOTE:
The layout of --disk_layouts is a bit complicated.
It's highly recommended that you generate it using --dry-run which will simulate an installation, without performing any damaging actions on your machine. (no formatting is done)

    {
        "/dev/loop0": {
            "partitions": [
                {
                    "boot": true,
                    "encrypted": false,
                    "filesystem": {
                        "format": "fat32"
                    },
                    "wipe": true,
                    "mountpoint": "/boot",
                    "size": "513MB",
                    "start": "5MB",
                    "type": "primary"
                },
                {
                    "btrfs": {
                        "subvolumes": {
                            "@.snapshots": "/.snapshots",
                            "@home": "/home",
                            "@log": "/var/log",
                            "@pkgs": "/var/cache/pacman/pkg"
                        }
                    },
                    "encrypted": true,
                    "filesystem": {
                        "format": "btrfs"
                    },
                    "wipe": true,
                    "mountpoint": "/",
                    "size": "100%",
                    "start": "518MB",
                    "type": "primary"
                }
            ],
            "wipe": true
        }
    }
The overall structure is that of { "blockdevice-path" : ...} followed by options for that blockdevice.
Each partition has it's own settings, and the formatting is executed in order (top to bottom in the above example).
Mountpoints is later mounted in order of path traversal, / before /home etc.

Key | Values | Description | Required
filesystem | { "format": "ext4 / btrfs / fat32 etc." } | Filesystem for root and other partitions | Yes
boot | <bool> | Marks the partition as bootable | No
encrypted | <bool> | Mark the partition for encryption | No
mountpoint | /path | Relative to the inside of the installation, where should the partition be mounted | Yes
start | <size><B, MiB, GiB, %, etc> | The start position of the partition | Yes
type | primary | Only used if MBR and BIOS is used. Marks what kind of partition it is. | No
btrfs | { "subvolumes": {"subvolume": "mountpoint"}} | Support for btrfs subvolumes for a given partition | No

DISCORD

There's a discord channel which is frequented by some contributors.
To join the server, head over to https://discord.gg/cqXU88y and join in.
There's not many rules other than common sense and to treat others with respect. The general chat is for off-topic things as well.

There's the @Party Animals role if you want notifications of new releases which is posted in the #Release Party channel. Another thing is the @Contributors role can be activated by contributors by writing !verify and follow the verification process.

Hop in, we hope to see you there! : )

ISSUE TRACKER & BUGS

Issues and bugs should be reported over at https://github.com/archlinux/archinstall/issues.

General questions, enhancements and security issues can be reported over there too. For quick issues or if you need help, head over to the Discord server which has a help channel.

  Log files
When submitting a help ticket, please include the /var/log/archinstall/install.log.
It can be found both on the live ISO but also in the installed filesystem if the base packages were strapped in.

TIP:
An easy way to submit logs is curl -F'file=@/var/log/archinstall/install.log' https://0x0.st.
Use caution when submitting other log files, but archinstall pledges to keep install.log safe for posting publicly!

There are additional log files under /var/log/archinstall/ that can be useful:

•   /var/log/archinstall/user_configuration.json - Stores most of the guided answers in the installer

•   /var/log/archinstall/user_credentials.json - Stores any usernames or passwords, can be passed to --creds

•   /var/log/archinstall/user_disk_layouts.json - Stores the chosen disks and their layouts

•   /var/log/archinstall/install.log - A log file over what steps were taken by archinstall

•   /var/log/archinstall/cmd_history.txt - A complete command history, command by command in order

•   /var/log/archinstall/cmd_output.txt - A raw output from all the commands that were executed by archinstall

    WARNING: We only try to guarantee that /var/log/archinstall/install.log is free from sensitive information. Any other log file should be pasted with utmost care!

PYTHON LIBRARY

Archinstall ships on PyPi as archinstall. But the library can be installed manually as well.

WARNING: These steps are not required if you want to use archinstall on the official Arch Linux ISO.

  Installing with pacman

Archinstall is on the official repositories. And it will also install archinstall as a python library.

To install both the library and the archinstall script:

    pacman -S archinstall

Alternatively, you can install only the library and not the helper executable using the python-archinstall package.

  Installing with PyPi

The basic concept of PyPi applies using pip.

    pip install archinstall

  Install using source code
You can also install using the source code.
For sake of simplicity we will use git clone in this example.

    git clone https://github.com/archlinux/archinstall

You can either move the folder into your project and simply do

    import archinstall

Or you can use setuptools to install it into the module path.

    sudo python setup.py install

PYTHON MODULE

Archinstall supports running in module mode. The way the library is invoked in module mode is limited to executing scripts under the example folder.

It's therefore important to place any script or profile you wish to invoke in the examples folder prior to building and installing.

  Pre-requisites

We'll assume you've followed the Install using source code method. Before actually installing the library, you will need to place your custom installer-scripts under ./archinstall/examples/ as a python file.

More on how you create these in the next section.

WARNING: This is subject to change in the future as this method is currently a bit stiff. The script path will become a parameter. But for now, this is by design.

  Creating a script

Lets create a test_installer - installer as an example. This is assuming that the folder ./archinstall is a git-clone of the main repo. We begin by creating ./archinstall/examples/test_installer.py. The placement here is important later.

This script can now already be called using python -m archinstall test_installer after a successful installation of the library itself. But the script won't do much. So we'll do something simple like list all the hard drives as an example.

To do this, we'll begin by importing archinstall in our ./archinstall/examples/test_installer.py and call some functions.

    import archinstall
    all_drives = archinstall.all_blockdevices(partitions=False)
    print(list(all_drives.keys()))

This should print out a list of drives. As an example, this will do just fine.

Now, go ahead and install the library either as a user-module or system-wide.

  Calling a module

Assuming you've followed the example in Creating a script, you can now safely call it with:

    python -m archinstall test_installer

This should now print all available drives on your system.

NOTE: This should work on any system, not just Arch Linux based ones. But note that other functions in the library rely heavily on Arch Linux based commands to execute the installation steps. Such as arch-chroot.

BINARY EXECUTABLE

Archinstall can be compiled into a standalone executable. For Arch Linux based systems, there's a package for this called archinstall.

WARNING: This is not required if you're running archinstall on a pre-built ISO. The installation is only required if you're creating your own scripted installations.

  Using pacman

Archinstall is on the official repositories.

    sudo pacman -S archinstall

  Using PKGBUILD

The source contains a binary PKGBUILD which can be either copied straight off the website or cloned using git clone https://github.com/Torxed/archinstall.

Once you've obtained the PKGBUILD, building it is pretty straight forward.

    makepkg -s

Which should produce an archinstall-X.x.z-1.pkg.tar.zst which can be installed using:

    sudo pacman -U archinstall-X.x.z-1.pkg.tar.zst

NOTE: For a complete guide on the build process, please consult the PKGBUILD on ArchWiki.

  Manual compilation

You can compile the source manually without using a custom mirror or the PKGBUILD that is shipped. Simply clone or download the source, and while standing in the cloned folder ./archinstall, execute:

    nuitka3  --standalone --show-progress archinstall

This requires the nuitka package as well as python3 to be installed locally.

BINARY EXECUTABLE

WARNING: The binary option is limited and stiff. It's hard to modify or create your own installer-scripts this way unless you compile the source manually. If your usecase needs custom scripts, either use the pypi setup method or you'll need to adjust the PKGBUILD prior to building the arch package.

The binary executable is a standalone compiled version of the library. It's compiled using nuitka with the flag --standalone.

  Executing the binary

As an example we'll use the guided installer. To run the guided installed, all you have to do (after installing or compiling the binary), is run:

    ./archinstall guided

As mentioned, the binary is a bit rudimentary and only supports executing whatever is found directly under ./archinstall/examples. Anything else won't be found. This is subject to change in the future to make it a bit more flexible.

ARCHINSTALL.INSTALLER

The installer is the main class for accessing an installation-instance. You can look at this class as the installation you have or will perform.

Anything related to inside the installation, will be found in this class.

archinstall.Installer(target: str, *, base_packages: List[str] | None = None, kernels: List[str] | None = None)
    Installer() is the wrapper for most basic installation steps. It also wraps pacstrap() among other things.

Parameters

•   partition (class:archinstall.Partition) -- Requires a partition as the first argument, this is so that the installer can mount to mountpoint and strap packages there.

•   boot_partition (class:archinstall.Partition) -- There's two reasons for needing a boot partition argument, The first being so that mkinitcpio can place the vmlinuz kernel at the right place during the pacstrap or linux and the base packages for a minimal installation. The second being when add_bootloader() is called, A boot_partition must be known to the installer before this is called.

•   profile (str, optional) -- A profile to install, this is optional and can be called later manually. This just simplifies the process by not having to call install_profile() later on.

•   hostname (str, optional) -- The given /etc/hostname for the machine.

ARCHINSTALL.PROFILE

This class enables access to pre-programmed profiles. This is not to be confused with archinstall.Application which is for pre-programmed application profiles.

Profiles in general is a set or group of installation steps. Where as applications are a specific set of instructions for a very specific application.

An example would be the (currently fictional) profile called database. The profile database might contain the application profile postgresql. And that's the difference between archinstall.Profile and archinstall.Application.

archinstall.Profile(installer: Installer | None, path: str)

ARCHINSTALL.APPLICATION

This class enables access to pre-programmed application configurations. This is not to be confused with archinstall.Profile which is for pre-programmed profiles for a wider set of installation sets.

archinstall.Application(installer: Installer | None, path: str)

    WARNING: All these helper functions are mostly, if not all, related to outside-installation-instructions. Meaning the calls will affect your current running system - and not touch your installed system.

PROFILE RELATED HELPERS

archinstall.list_profiles(filter_irrelevant_macs: bool = True, subpath: str = '', filter_top_level_profiles: bool = False) -> Dict[str, Dict[str, str | bool]]

PACKAGES

archinstall.find_package(package: str) -> List[PackageSearchResult]

archinstall.find_packages(*names: str) -> Dict[str, Any]
    This function returns the search results for many packages. The function itself is rather slow, so consider not sending to many packages to the search query.

LOCALE RELATED

archinstall.list_keyboard_languages() -> Iterator[str]

archinstall.search_keyboard_layout(layout: str) -> Iterator[str]

archinstall.set_keyboard_language(locale: str) -> bool

SERVICES

archinstall.service_state(service_name: str) -> str

MIRRORS

archinstall.filter_mirrors_by_region(regions: str, destination: str = '/etc/pacman.d/mirrorlist', sort_order: List[str] = ['https', 'http'], *args: str, **kwargs: str) -> bool | bytes
    This function will change the active mirrors on the live medium by filtering which regions are active based on regions.

Parameters
    regions (str) -- A series of country codes separated by ,. For instance SE,US for sweden and United States.

archinstall.add_custom_mirrors(mirrors: List[str], *args: str, **kwargs: str) -> bool
    This will append custom mirror definitions in pacman.conf

Parameters
    mirrors (dict) -- A list of mirror data according to: {'url': 'http://url.com', 'signcheck': 'Optional', 'signoptions': 'TrustAll', 'name': 'testmirror'}

archinstall.insert_mirrors(mirrors: Dict[str, Any], *args: str, **kwargs: str) -> bool
    This function will insert a given mirror-list at the top of /etc/pacman.d/mirrorlist. It will not flush any other mirrors, just insert new ones.

Parameters
    mirrors (dict) -- A dictionary of {'url' : 'country', 'url2' : 'country'}

archinstall.use_mirrors(regions: Mapping[str, Iterable[str]], destination: str = '/etc/pacman.d/mirrorlist') -> None

archinstall.re_rank_mirrors(top: int = 10, src: str = '/etc/pacman.d/mirrorlist', dst: str = '/etc/pacman.d/mirrorlist') -> bool

archinstall.list_mirrors(sort_order: List[str] = ['https', 'http']) -> Dict[str, Any]

DISK RELATED

archinstall.BlockDevice(path: str, info: Dict[str, Any] | None = None)

archinstall.Partition(path: str, block_device: BlockDevice, part_id: str | None = None, filesystem: str | None = None, mountpoint: str | None = None, encrypted: bool = False, autodetect_filesystem: bool = True)

archinstall.Filesystem(blockdevice: BlockDevice, mode: int)

archinstall.device_state(name: str, *args: str, **kwargs: str) -> bool | None

archinstall.all_blockdevices(mappers: bool = False, partitions: bool = False, error: bool = False, exclude_iso_dev: bool = True) -> Dict[str, Any]
    Returns BlockDevice() and Partition() objects for all available devices.

LUKS (DISK ENCRYPTION)

archinstall.luks2(partition: Partition, mountpoint: str | None, password: str | None, key_file: str | None = None, auto_unmount: bool = False, *args: str, **kwargs: str)

NETWORKING

archinstall.get_hw_addr(ifname: str) -> str

archinstall.list_interfaces(skip_loopback: bool = True) -> Dict[str, str]

archinstall.check_mirror_reachable() -> bool

archinstall.update_keyring() -> bool

archinstall.enrich_iface_types(interfaces: Dict[str, Any] | List[str]) -> Dict[str, str]

archinstall.get_interface_from_mac(mac: str) -> str

archinstall.wireless_scan(interface: str) -> None

archinstall.get_wireless_networks(interface: str) -> None

GENERAL

archinstall.log(*args: str, **kwargs: str | int | Dict[str, str | int]) -> None

archinstall.locate_binary(name: str) -> str

archinstall.SysCommand(cmd: str | List[str], callbacks: Dict[str, Callable[[Any], Any]] | None = None, start_callback: Callable[[Any], Any] | None = None, peek_output: bool | None = False, peak_output: bool | None = False, environment_vars: Dict[str, Any] | None = None, working_directory: str | None = './', remove_vt100_escape_codes_from_lines: bool = True)

archinstall.SysCommandWorker(cmd: str | List[str], callbacks: Dict[str, Any] | None = None, peek_output: bool | None = False, peak_output: bool | None = False, environment_vars: Dict[str, Any] | None = None, logfile: None | None = None, working_directory: str | None = './', remove_vt100_escape_codes_from_lines: bool = True)

EXCEPTIONS

archinstall.RequirementError()
    Common base class for all exceptions

archinstall.DiskError()
    Common base class for all exceptions

archinstall.ProfileError()
    Common base class for all exceptions

archinstall.SysCallError(message: str, exit_code: int | None = None, worker: SysCommandWorker | None = None) -> None
    Common base class for all exceptions

archinstall.ProfileNotFound()
    Common base class for all exceptions

archinstall.HardwareIncompatibilityError()
    Common base class for all exceptions

archinstall.PermissionError()
    Common base class for all exceptions

archinstall.UserError()
    Common base class for all exceptions

archinstall.ServiceException()
    Common base class for all exceptions

AUTHOR
Anton Hvornum

COPYRIGHT
2024, Anton Hvornum