This guide shows you how to use the scripts in this repo to compile MassOS from source.

This guide is aimed at developers (see below). Most users won't want to compile MassOS themselves. If you aren't a developer and want to install MassOS normally, look at Installing MassOS.

Please read all of these carefully before settling on the decision to compile MassOS:

• Building MassOS takes a very long time, and the speed will vary massively depending on your CPU. The fastest CPUs will take a few hours to compile MassOS, however the build could take several days on slower systems. While we cannot test every CPU, the time measured of a stage 2 build to complete on a few different CPUs can be seen below.

• The minimum amount of RAM needed to compile MassOS is based on how many threads your CPU has. You must have twice as much RAM as CPU threads. For example, if you have a CPU with 16 threads, you must have at least 32GB of RAM. Run nproc if you are unsure how many threads your CPU has, and free -h if you are unsure how much RAM you have. Swap space can be used as a RAM alternative, if you are unable to satisfy this requirement via physical memory, however the build process may be significantly slowed down if the machine has to swap (and your disk may wear out more quickly if it's an SSD), so use it with caution.

• The build requires at least 30GB of free disk space. Even though the final produced build is much smaller, the build process itself can take up a large amount of space.

• The second and third parts of the build (Stage 2 and Stage 3) must be run with root access, due to the fact that they make use of a chroot environment with mounted virtual filesystems. No alternatives are currently supported.

• MassOS must be built from an existing GNU/Linux system. Although the build process is heavily bootstrap-based, we strongly recommend building from an existing installation of MassOS itself to keep the system robust and ensure there will not be any influence from a non-MassOS distribution. Additionally, MassOS contains all the necessary dependencies included for bootstrapping in Stage 1, as well as running the Live CD creation script afterwards, so no additional dependencies will have to be manually installed. While it should, theoretically, be possible to build from any modern distro, we require that all official release builds are built from MassOS - more about this requirement can be seen below. Please note that if you choose to build from a non-MassOS distribution, it must be a very recent and up-to-date distribution (for example, the latest interim/non-LTS release of Ubuntu). Furthermore, the system CANNOT, UNDER ANY CIRCUMSTANCE, be running a Linux kernel older than 5.10. This is because MassOS configures Glibc (the core C library) to only support 5.10 and newer kernel versions. This means that the MassOS system, in its entirety, will NOT build from or run on older kernels. This requirement is not an issue for MassOS itself, as the very first version of MassOS released back in 2021 launched with Linux 5.13, so MassOS has never supported older kernels than 5.10 anyway. There are no plans to bump this requirement higher than 5.10 in the forseeable future.

ADDITIONAL NOTE: Your CPU may be limited by default in order save power. If you are using a distribution that makes use of power-profiles-daemon (MassOS included), it is strongly recommended that you ensure the power profile is set to performance. You can do this with the following command:

powerprofilesctl set performance

This table lists various CPUs, and how long the Stage 2 build process took to complete based on the latest development branch sources as of 2025-06-01. Unless otherwise stated, all builds used an up-to-date MassOS (Xfce) installation with the power mode in power-profiles-daemon set to performance (see above), and no other applications being used during the build (the machine is left alone the entire time).

Now you've read the above notices and are fully aware of what you're getting yourself into, you can proceed with building MassOS.

In order to build MassOS, you will first need to clone the GitHub repository locally. To do so, run the following commands:

git clone --recursive https://github.com/MassOS-Linux/MassOS
cd MassOS

This will checkout the current development version of MassOS. Note that, since it is in development, the build is not guaranteed to successfully complete and may exit unsuccessfully. If this occurs, please open an issue to report the problem.

During the experimental phase of MassOS, it is not currently possible to build stable releases. But a build is made for most commits which are pushed to the development branch, so your build should succeed.

MassOS has recently added support for secure boot. A requirement of this is that each build of MassOS must be able to use a secure boot key/certificate set for signing EFI binaries, the kernel, and the kernel modules which are part of the build.

The official MassOS key is not made public for use by custom builders, but you can generate your own key set by running the following command:

./generate-sb-keys.sh

This script will prompt you to enter your desired CN (Common Name) for the secure boot key set. You can enter whatever you want, but we recommend making it descriptive, for example: John Smith Secure Boot Key.

The newly key set will be placed to the keys/secureboot/ directory of the MassOS source tree. You can save this somewhere else, so as to be able to re-use it for future builds. But DO NOT SHARE IT, as it contains the private signing key (db.key), which should never be shared with anyone. If you do want to share your secure boot signing certificates, so that users can more easily import your certificate into their UEFI firmware, then you can share all the other db.* files, but DO NOT SHARE the db.key file. The purpose of each db.* file is described in keys/README.md in the MassOS source tree. The certificate files, which can be shared publicly, will be embedded in the final built system (at /usr/share/massos/certs/secureboot/), and will be embedded in the bootable section of the Live ISO image if you create one, so that users can directly import it into their firmware from their bootable USB flash drive.

If you want to utilize secure boot with MassOS on your own computer, or simply want to learn more about how MassOS implements secure boot support from the perspective of end-users, then please read the article named UEFI Secure Boot. You may also be interested in taking control of your PC's secure boot environment.

Before you can begin the compiling process of MassOS, you must first download the source tarballs of all the software which make up the MassOS system. Fortunately, this command will automatically download them all for you:

./retrieve-sources.sh

NOTE: Ensure everything downloaded successfully. If the final message says something along the lines of "Some downloads may have failed", then you MUST NOT continue until all the downloads were successful. You can re-run the retrieve-sources.sh script to retry the download of the missing files (it won't re-download anything already successfully downloaded). Sometimes a download fails because the server hosting the source tarball is down, or it used to provide the file but has now decided to stop providing it for some reason. In this case, you will need to edit the offending URL in the source-urls file to a mirror which also hosts the same file.

Optionally, you can verify the integrity of the downloaded sources by running the following command:

./verify-sources.sh

The first part of the build process involves using the host system to build a temporary bootstrap toolchain, including a compiler, linker, and C library. This has to be done on the host system since a compiler can only be compiled using an existing compiler. This is also the reason why building from MassOS as the host system is strongly encouraged, even though the bootstrap process should eliminate as much influence from the host system as possible. Build the bootstrap system by running the following command:

./stage1.sh

Now the temporary tools have successfully been built, you can proceed with building the full MassOS system. This must be run as root since it makes use of a chroot environment with mounted virtual filesystems. Also, be aware that this is the part which takes the longest:

sudo ./stage2.sh

If, for some reason, the build fails and exits unsuccessfully, all is not lost. The MassOS build system has a "resume" functionality for Stage 2 and Stage 3. To use it, you will first need to inspect the build output to determine which point your build failed at. Once you have determined this, you must edit the build-system.sh script at the location massos-rootfs/sources/build-system.sh (not the one at the top level of the MassOS source tree, unless you are fixing a failure caused by it). Once you've edited it, remove lines 26 up to where the failure occurred. You can automate this with the command sed -i 26,XXXd massos-rootfs/sources/build-system.sh, where XXX gets replaced with the line number you are removing up to. Then, attempt to resume the build by running the following command:

sudo ./stage2-resume-failed.sh CONFIRM_STAGE2_RESUME=YES

If all goes well, the build should then pick up from where it left off and continue until it finishes successfully. Note that, however, in some cases, the failure could be caused by a broken dependency chain earlier in the build system, and in this case, it may be more advisable to restart the entire build process from the beginning (after fixing the problem, of course), by removing the massos-rootfs directory.

Once the core system is built, you can compile a desktop environment and finish the build. You once again have to run this as root, replacing <desktop> with a desktop environment in the stage3 folder (see stage3/README for more details). Use nodesktop if you want a command-line only build.

sudo ./stage3.sh <desktop>

For example, for Xfce:

sudo ./stage3.sh xfce

The same rule for resuming a failed build applies here as it did for Stage 2; the script is named stage3-resume-failed.sh.

When the MassOS system is completely build and finished, an output tarball labelled massos-<VERSION>-rootfs-x86_64-<DESKTOP>.tar.xz will be created. As of the latest upstream commit, it should no longer be needed to manually change ownership back to your unprivileged user (as the build scripts will try to do it automatically), but if it fails for some reason (i.e., outputs chmod errors at the end of stage 3), then you could manually change ownership using the following command:

sudo chown $(whoami):$(whoami) massos-*.tar.zst{,.b2}

To create a Live CD ISO image for the build, run the following command, replacing <rootfs-filename> with the full name of the rootfs tarball:

sudo ./create-livecd.sh <rootfs-filename>.tar.zst

As with the main rootfs, the produced ISO file should automatically have its ownership changed back to your unprivileged user by the create-livecd.sh script. However, if it fails for some reason, you can again change it back manually:

sudo chown $(whoami):$(whoami) massos-*.iso{,.b2}