EndeavourOS-ISO: building the installer image behind an Arch based distribution

An Arch-ISO fork, not a distribution in itself

The repository is described in one line as an EndeavourOS ISO framework based on Arch-ISO, and that one line sets the scope. This is not a Linux distribution. It is the machinery that produces the installation environment for EndeavourOS, which is itself an Arch based distribution with its own repositories, mirrors and community.

The readme is explicit that the ISO is based on hugely modified Arch-ISO to provide the Installation Environment for EndeavourOS, and it names the two base sources it is derived from: Arch-ISO, the upstream project that builds Arch installation images, and Calamares, the installer framework, hosted on Codeberg. Alongside those it lists the two development sources that are EndeavourOS specific: the EndeavourOS-ISO repository itself, described as the live environment with the KDE desktop, and a Calamares fork maintained by the EndeavourOS team.

That fork of Calamares is the part with real content in it. The base Calamares project provides the installer, and the fork changes how it looks and behaves for EndeavourOS. The readme gives a concrete example of what that means: for releases older than Galileo, the change to KDE means those images use an XFCE4 live session, and to get the old style theming you have to build Calamares manually with a specific PKGBUILD and drop the resulting package into the ISO structure.

The maintenance badge in the readme header says yes with a 2026 date, and the branch policy is stated plainly: the main branch is development latest and unstable. The named developers are joekamprad, manuel and fernandomaroto, with fernandomaroto credited as the initial developer, and the contributors section points at the Open Collective community, which tells you how the project is funded.

The last push was on 2026-09-27 and the repository has no GitHub releases, so the tags and the changelog are the release history.

Building the image, step by step

The build instructions are concrete and assume a particular kind of machine. You need an installed EndeavourOS system, or any Arch based system with the EndeavourOS repository enabled, because the installer packages and the needed dependencies are installed from the EndeavourOS repository rather than from this tree.

The build dependencies go in first.

sudo pacman -S archiso git squashfs-tools --needed

The readme recommends rebooting after those changes.

Next comes prepare. There are two ways in, and the difference matters. If you want the last release state rather than the development head, you download a specifically tagged tarball from the tags page, and there is a warning not to use the zip tarball because that causes issues with symlinks.

wget https://github.com/endeavouros-team/EndeavourOS-ISO/archive/refs/tags/23.11.1.2.tar.gz
tar -xvf 23.11.1.2.tar.gz
cd "EndeavourOS-ISO-23.11.1.2"
./prepare.sh

Otherwise you clone and take the unstable development branch.

git clone https://github.com/endeavouros-team/EndeavourOS-ISO.git
cd EndeavourOS-ISO
./prepare.sh

The actual image build is mkarchiso, which is the Arch-ISO script the repository carries in its root directory.

sudo ./mkarchiso -v "."

There is a variant that captures the log to a timestamped file, which is the one to use when the build fails and you need the output later.

sudo ./mkarchiso -v "." 2>&1 | tee "eosiso_$(date -u +'%Y.%m.%d-%H:%M').log"

The finished .iso file appears in the out directory. The readme also tells you to read the changelog before starting, to learn about the latest changes, and points to the EndeavourOS development documentation for general information.

What the shell scripts in the root actually do

The repository root is short and every file in it has a job, which makes the structure the clearest documentation of the build.

prepare.sh and prepare_auto.sh are the entry points you invoke. reset.sh is the counterpart, and the readme does not describe what it does, so it is worth reading before you run it. mkarchiso is the Arch-ISO build script, and mkarchiso-changes.md is the record of how this repository has modified it, which is the most direct evidence of the hugely modified claim in the readme.

profiledef.sh and profiledef.sh_auto are the profiles, and the two are the reason the project can ship more than one variant of the live environment. The profiledef files tell archiso what to put in the image and how to boot it, and the automatic variant is what produces the newer desktop session while the plain one serves the older XFCE4 based sessions. run_before_squashfs.sh is a hook that runs before the filesystem image is squashed, which is where you would put anything that has to be baked into the live environment before it is compressed.

Then there are the data files. airootfs/ is the root filesystem tree of the live image, and it is where the package list and the extra packages live. efiboot/ holds the UEFI boot artefacts and syslinux/ holds the BIOS ones, which is how the same image boots on both kinds of machine. mirrorlist and pacman.conf configure what the live environment can install and from where.

The final piece is packages.x86_64, the list of packages included in the image for the 64-bit architecture. The readme mentions this file directly in the older release instructions: to use a manually built Calamares package you have to remove calamares from packages.x86_64 before starting the ISO build. That is a concrete example of the constraint that runs through the whole project. The image contents are declared in a text file, and any deviation between what you have built and what the image expects has to be reconciled by editing that file.

Both boot paths, and the naming scheme for images

Two details in the readme are worth separating out, because they are the parts a user actually consumes.

The first is the boot support. The readme shows systemd-boot for UEFI systems and BIOS boot with syslinux for legacy systems, each with a diagram from the project's screenshot repository. The efiboot/ and syslinux/ directories in the root are the two halves of that arrangement. Supporting both means the ISO has to carry two boot loaders, and a builder who changes anything in one of those directories has to know the other is still consistent.

The second is the file naming. The general ISO naming pattern is given as EndeavourOS_RELEASENAMEREBUILD-YYYY.MM.DD.iso, with an example of EndeavourOS_Galileo-Neo-2024.01.25.iso. The README breaks down the parts: YYYY.MM.DD is the date of the release, and REBUILD is either empty, -Neo or -Nova.

That naming scheme is doing real work, because the repository has no GitHub releases, only tags, and the image names carry the machine readable record of what went into each build. The release name identifies the desktop, the rebuild suffix identifies the rebuild counter, and the date identifies the build. For a distribution that pushes to main continuously, that convention is how someone months later knows which image to fetch.

The screenshots referenced in the readme for the boot options and the KDE live session come from a separate screenshots repository, which is a small sign of how the project is organised: the code, the images and the documentation are split across repositories rather than kept in one place.

The resources section points to the project website, the forum for getting help, a bug report thread on the forum for installation issues, and a Telegram help chat. The bug report location is notable: installation problems are handled in a forum thread rather than in the issue tracker of this repository, which suggests this repository is for builders and the support load sits with the distribution's own channels.

Where EndeavourOS-ISO is the wrong tool

There are three clear reasons not to reach for this repository, and one case where it is exactly right.

The first wrong case is installing EndeavourOS. If you want to install the distribution, you download a released image, and this repository is how those images are made, not how they are obtained. Building one from source to install it is possible but strictly harder than fetching a build.

The second is building a custom image for a machine that is not an EndeavourOS or Arch based system. The readme is clear that you need an installed EndeavourOS system or any Arch based system with the EndeavourOS repository enabled, because the installer packages and needed dependencies come from the EndeavourOS repository. The build is not self contained and it does not run on, say, a Debian machine, and the pacman-based dependency handling means the tooling is Arch shaped throughout.

The third is the moving base. The main branch is explicitly unstable development state, and the base it modifies is Arch-ISO plus a fork of Calamares, both of which move on their own schedules. A build that worked last month can fail today because upstream changed underneath it, which is exactly why the readme tells you to read the changelog first and why mkarchiso-changes.md exists as a running record. This is normal for an image pipeline and it is also a real cost for anyone who needs a reproducible image without pinning a tag.

The case where it is the right tool is a maintainer who needs to reproduce a specific released image, or who wants to see how a Calamares based installer is put together and packaged. The tagged tarball path exists for exactly that, and the documentation points to the EndeavourOS development documentation for the surrounding workflow.

On the alternative, the difference in approach against building on Arch-ISO directly is the layer of EndeavourOS specific change: the Calamares fork, the desktop session selection, the boot setup for both UEFI and BIOS, and the profile handling for the automatic variant. Building on Arch-ISO gives you the upstream script and nothing else, which means you write the profile, you choose the desktop, you configure the boot loader and you build the Calamares package with the right theming. Using this repository gives all of that as a maintained starting point, and the cost is that you inherit a dependency on the fork and on the profile scheme, so when the Calamares fork changes, your build changes with it unless you pin a tag.

The second alternative is the live session approach in general. A distribution can ship a small installer image that downloads packages over the network during installation, rather than baking everything into a several gigabyte ISO. That is a different trade in the same direction: the live image is smaller and the packages are current at install time, and the cost is that installation needs a working network connection and the image cannot install onto a machine with no network.

Editorial conclusion

EndeavourOS-ISO suits a maintainer who needs to reproduce an EndeavourOS installation image on their own hardware, or who wants to understand how a Calamares based installer is assembled and packaged. It does not suit an end user who wants to install EndeavourOS, because the released images are built elsewhere, and it does not suit a builder who is not prepared to chase the base image and the Calamares fork as they move. Before you start, read the changelog the readme points you at, and check that your system matches the EndeavourOS repository setup the build expects, since the installer packages are pulled from the distribution repository rather than from this tree.

Frequently asked questions

Official sources

1. endeavouros-team/EndeavourOS-ISO on GitHub
2. Issues
3. License: GPL-3.0
4. README