From ArchWiki
Jump to navigation Jump to search

Archiso is a tool for building Arch Linux live CD ISO images. The official images are built with Archiso. Archiso is configurable and can be used as the basis for different systems, for example rescue systems, or linux installers. This wiki article explains how to install Archiso, and how to configure it to control aspects of the resulting ISO image such as included packages and files. Technical requirements and build steps can be found in the official project documentation. Archiso is implemented with a number of bash scripts. The core component of Archiso is the mkarchiso command. Its options are documented in its usage output and not covered here. Users do not need to interface with mkarchiso directly.


Note: It is recommended to act as root in all the following steps. If not, it is very likely to have problems with false permissions later.

Install the archiso or archiso-gitAUR package.

Archiso comes with two "profiles", releng and baseline.

  • Use releng if you wish to create a fully customized live version of Arch Linux, pre-installed with all your favorite programs and configurations. This profile is also used for building an official Arch Linux ISO.
  • Use baseline if you just want to create the most basic live medium, with no pre-installed packages and a minimalistic configuration.

Use the following command to copy the profile of your choice to a directory. Replace profile with either releng or baseline, and replace archlive with a directory name of your choice.

# cp -r /usr/share/archiso/configs/profile/ archlive

Now proceed to different sections depending on the chosen profile and your goal.

  • releng: If you chose the releng profile, and
  • baseline: If you chose the baseline profile then proceed onto #Build the ISO.

Configure the live medium

This section details how to configure the image, and define the packages and configurations that will be copied to the image later.

Inside the archlive directory created in #Setup there are a number of files and directories; we are only concerned with the following ones:

  • packages.x86_64 - this file lists the packages that are installed on the live system image.
  • airootfs - this directory acts as an overlay and allows you to make customizations.

Any administrative task that you would do while following the installation guide (or after installation) can be scripted by editing archlive/airootfs/root/, except for package installation. The script is written from the perspective of the running live system, i.e. in the script the path / refers to the root of the running live system.

Installing packages

Edit the lists of packages in packages.x86_64 to configure which packages are installed on the live system image, listing packages line by line.

Note: If you want to use a window manager in the Live CD then you must add the necessary and correct video drivers, or the WM may freeze on loading.

Custom local repository

For the purpose of preparing custom packages or packages from AUR/ABS, you could also create a custom local repository. You can then add your repository by putting the following into archlive/pacman.conf, above the other repository entries (for top priority):

# custom repository
SigLevel = Optional TrustAll
Server = file:///path/to/customrepo/$arch

Installing packages from multilib

To install packages from the multilib repository simply uncomment the repository in archlive/pacman.conf:

SigLevel = PackageRequired
Include = /etc/pacman.d/mirrorlist

Adding files to image

Note: You must be root to do this, do not change the ownership of any of the files you copy over, everything within the airootfs directory must be root owned. Proper ownerships will be sorted out shortly.

The airootfs directory acts as an overlay, think of it as root directory '/' on your current system, so any files you place within this directory will be copied over on boot-up.

So if you have a set of iptables scripts on your current system you want to be used on you live image, copy them over as such:

# cp -r /etc/iptables archlive/airootfs/etc

Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. As an example the /etc/X11/xinit/xinitrc configuration file resides on a path that might be overwritten by installing a package. To place the configuration file one should put the custom xinitrc in archlive/airootfs/etc/skel/ and then modify to move it appropriately.

Boot loader

The default file should work fine, so you should not need to touch it.

Due to the modular nature of isolinux, you are able to use lots of addons since all .c32 files are copied and available to you. Take a look at the official syslinux site and the archiso git repo. Using said addons, it is possible to make visually attractive and complex menus. See [1].

UEFI Secure Boot

If you want to make your Archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed boot loader. You can follow the instructions on Secure Boot#Booting an installation medium.

Login manager

Starting X at boot is done by enabling your login manager's systemd service. If you know which .service file needs a softlink: Great. If not, you can easily find out in case you are using the same program on the system you build your iso on. Just use:

$ ls -l /etc/systemd/system/display-manager.service

Now create the same softlink in archlive/airootfs/etc/systemd/system. For LXDM:

# ln -s /usr/lib/systemd/system/lxdm.service archlive/airootfs/etc/systemd/system/display-manager.service

This will enable LXDM at system start on your live system.

Alternatively you can just enable the service in airootfs/root/ along with other services that are enabled there.

Changing automatic login

The configuration for getty's automatic login is located under airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf.

You can modify this file to change the auto login user:

ExecStart=-/sbin/agetty --autologin isouser --noclear %I 38400 linux

Or remove it altogether to disable auto login.

Build the ISO

Now you are ready to turn your files into the .iso which you can then burn to CD or USB.

Inside the archlive directory, execute:

# ./ -v

The script will now download and install the packages you specified to work/*/airootfs, create the kernel and init images, apply your customizations and finally build the iso into out/.

Rebuild the ISO

Rebuilding the iso after modifications is not officially supported. However, it is easily possible by applying two steps. First you have to remove lock files in the work directory:

# rm -v work/build.make_*

Tango-view-refresh-red.pngThis article or section is out of date.Tango-view-refresh-red.png

Reason: is deprecated.[2] (Discuss in Talk:Archiso#)

If you have edited airootfs/root/ to create an unprivileged user, the rebuild will fail when creating it because the user will already exist (FS#41865). To avoid this issue, you need to check if the user exists before running useradd, e.g. by running id:

! id arch && useradd -m -p "" -g users -G "adm,wheel,uucp" -s /usr/bin/zsh arch

Also remove persistent data such as created users or symlinks such as /etc/sudoers.

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Report more data that needs to be removed or reset. (Discuss in Talk:Archiso#)

Rebuilds can be sped up slightly by editing the pacstrap script (located at /bin/pacstrap) and changing the following at line 372:


if ! unshare --fork --pid pacman -r "$newroot" $pacmode "${pacman_args[@]}"; then


if ! unshare --fork --pid pacman -r "$newroot" $pacmode --needed "${pacman_args[@]}"; then

This increases the speed of the initial bootstrap, since it does not have to download and install any of the base packages that are already installed.

Removal of work directory

The temporary files are copied into work directory. If it happens that the script is interrupted, make sure there are no mount binds before deleting it - otherwise, you may lose data (e.g. an external device mounted at /run/media/$user/$label gets bound within work/x86_64/airootfs/run/media/$user/$label during the build process).

Using the ISO

See Installation guide#Boot the live environment for various options.

Run the ISO in QEMU

Install the optional dependencies qemu and edk2-ovmf.

Use the convenience script run_archiso to run a built image using QEMU.

$ run_archiso -i /path/to/

The virtual machine can also be run using UEFI emulation:

$ run_archiso -u -i /path/to/

See also

Documentation and tutorials

Creating a offline installation ISO

Find a previous version of an ISO image