archinstall: the guided Arch Linux installer and the Python library behind it

What archinstall does that the manual installation guide does not

The Arch Linux installation guide is a sequence of commands you type yourself: partition the disk, format, mount, pacstrap, generate fstab, chroot, configure the bootloader. archinstall replaces that sequence with a menu-driven flow and, in the same codebase, exposes the same operations as a Python library. The README describes it as a guided and automated installer that "doubles as a python library to install Arch Linux and manage services, packages, and other things inside the installed system", usually from a live medium or an existing installation.

The audience is therefore two different groups. The first is someone who wants Arch installed without transcribing a wiki page, and who is willing to accept the installer's defaults for filesystems, bootloader and profile. The second is someone automating installs: a lab, a VM fleet, a reproducible workstation build. For the second group the library and the declarative JSON path matter more than the menus, because the menus are not scriptable in any meaningful sense.

How the guided flow, JSON configuration and credentials file fit together

The default entry point is the guided script. Running archinstall with no arguments starts it, and the README notes that when you run from the ISO or from a pip install, archinstall "will use the guided script by default". Other flows are selected with --script <name>, and the examples directory carries the scripts that show how: interactive_installation.py, full_automated_installation.py, minimal_installation.py, only_hd_installation.py and auto_discovery_mounted.py.

Configuration is split in two files, and the split is deliberate. user_configuration.json holds general installation settings. user_credentials.json holds the sensitive parts: user password, root password and encryption password. The README states that account credentials are hashed with yescrypt and only the hash is written to the saved credentials file, but that this is not possible for the disk encryption password, which "needs to be stored in plaintext to be able to apply it". That is a property of full-disk encryption, not a defect in archinstall, but it means the credentials file is the one artefact you must handle carefully. To soften it, the installer offers to encrypt the whole credentials file when saving, and there are three ways to supply the decryption key at load time: the --creds-decryption-key argument, the ARCHINSTALL_CREDS_DECRYPTION_KEY environment variable, or an interactive prompt if neither is present.

The configuration files can be generated rather than written by hand: start archinstall, walk the menus, then choose Save configuration. The README points to examples/config-sample.json and examples/creds-sample.json as references, and the repository ships a schema.json at the top level, which is the practical way to check a hand-edited file before feeding it to an unattended install.

Installing archinstall and running a first guided installation

On the Arch live ISO you are root by default, so no sudo is needed there. The README gives this three-command sequence for getting the packaged version and starting it:

pacman-key --init
pacman -Sy archinstall
archinstall

What you should see is the guided menu. The first entry switches language; the README warns that not all languages are fully translated and that each one shows how much has been translated. If your language uses a non-Latin character set, the ISO does not ship every console font, and the README says to set one manually from /usr/share/kbd/consolefonts, for example with setfont LatGrkCyr-8x16.

If you would rather run the current code than whatever the ISO was built with, the README offers the git route, which it calls better because you get the latest code regardless of build date:

git clone https://github.com/archlinux/archinstall
cd archinstall
python -m archinstall $@

Note the version constraint in pyproject.toml: requires-python is ">=3.14". Running from git therefore depends on the Python on your live medium satisfying that, which is not something the README addresses.

For a repeatable install, save your configuration from the menus and then replay it:

archinstall --config <path to user config file or URL> --creds <path to user credentials config file or URL>

Both arguments accept a URL as well as a path, which is what makes network-hosted install profiles possible. If the credentials file was encrypted at save time, add --creds-decryption-key <password> or export ARCHINSTALL_CREDS_DECRYPTION_KEY before running.

The upgrade path on a live medium, and where it breaks

Upgrading archinstall on the ISO is not a package reinstall. The README is explicit that it "needs to be done via a full system upgrade", meaning pacman -Syu. That is a consequence of Arch's rolling model: the installer depends on the rest of the system being consistent with it.

The failure mode the README calls out is space. When booting from a live USB, the ramdisk has limited room, and there may not be enough to reinstall or upgrade the installer. Two remedies are given: resize the root partition following the Archiso documentation on adjusting the size of the root file system, or boot with the parameter copytoram=y, which copies the root filesystem to tmpfs. The second option trades RAM for space and is the one to reach for on a machine with memory to spare.

This is the point where archinstall's convenience has a real cost. A user who boots an old ISO, finds a bug, and tries to update the installer in place can end up in a state where the update cannot complete. The README documents the workarounds but does not document rollback, so there is no supported way back to the ISO's original installer once a partial upgrade has run.

Where archinstall is the wrong tool

The guided installer is built around choices that fit a normal machine. If your target is a layout the menus cannot express, or a storage arrangement that needs decisions the guided flow does not ask about, archinstall will either refuse the configuration or produce something you did not intend. The manual installation guide exists precisely for that case, and the README does not claim otherwise.

There is a second, subtler mismatch. Because archinstall also exposes everything as a library, it is tempting to treat it as a general system-provisioning framework. The README frames the library use as installing Arch and managing services, packages and other things "inside the installed system", usually from a live medium or an existing installation. That is narrower than configuration management. It does not replace a tool that converges an existing running system toward a declared state over time, and the examples in the repository are installation scripts, not ongoing configuration.

The third limitation is environmental. Translations are community-contributed and incomplete by design, and console fonts for non-Latin scripts are not all on the ISO. If your install workflow depends on a specific language being fully translated, the README gives you no guarantee, only a per-language indicator of coverage.

archinstall versus the manual installation procedure

The honest comparison is not archinstall against another installer, because the alternative that Arch users actually weigh is the wiki procedure itself. The difference is where the decisions live.

With the manual route, every decision is a command you type and can read back: you choose the partition table, you run mkfs with the filesystem you want, you run pacstrap with the package set you want, you write the fstab and the bootloader configuration yourself. Nothing is inferred. The cost is time and the risk of a typo at a step you cannot easily undo.

With archinstall, the decisions move into a menu or a JSON file. The installer performs the partitioning, formatting and bootloader setup for you. The benefit is speed and repeatability: a saved user_configuration.json plus user_credentials.json reproduces an install, which the manual procedure does not give you without writing your own script. The cost is that the reasoning behind each step is hidden. When something goes wrong, the README directs you to attach /var/log/archinstall/install.log to the issue, and archinstall share-log uploads it and returns a shareable URL. That log is the substitute for the transcript you would have had by hand.

Licence, maintenance and the cost of tracking a rolling installer

archinstall is GPL-3.0, and pyproject.toml states the licence as "GPL-3.0-only". If you embed it in a product or ship a modified ISO, that licence governs what you can do with the combined work; this is a description of the terms in the repository, not legal advice, and anyone redistributing a modified installer should read the licence text in LICENSE rather than rely on a summary.

The maintenance picture is straightforward from the repository: it is not archived, and the last push was on 2026-09-21. Releases are frequent, with 4.2 on 2026-04-15, 4.3 on 2026-04-20 and 4.4 on 2026-06-28. The version in pyproject.toml is 4.4, matching the latest release.

The upgrade cost is real for anyone pinning to a config file. The project depends on pydantic>=2.13.4, textual>=8.2.8 and other libraries, and the Python floor is 3.14. A saved configuration that works on 4.4 may need revalidation against schema.json after a major bump, and the README's advice to regenerate configuration files from the menus rather than hand-maintain them is the cheaper path if you are not automating. The install log at /var/log/archinstall/install.log is the first thing to check after any version change, since it records what the installer actually did with your configuration.

Editorial conclusion

archinstall suits anyone installing Arch on a single machine with a conventional disk layout, and it is the fastest route to a working system for people who do not want to follow the manual installation guide. It is the wrong tool if you need a layout the guided menus cannot express, or if you want to understand every step of the install: the manual wiki procedure still teaches that. Before relying on it, verify that the ISO you booted carries the version you expect, check the version field in your saved user_configuration.json against the schema, and confirm the credentials file is either encrypted or stored somewhere you are willing to leave a plaintext disk-encryption password.

Frequently asked questions

Official sources

1. archlinux/archinstall on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases