Installing MassOS
This page will guide you through the installation process of MassOS using the Live CD ISO file.
Before installing, you may wish to read About MassOS to find out more about the operating system, what its goals are, and its differences compared to other distributions of GNU/Linux.
NOTE: This guide is dedicated to installing MassOS using the Live CD ISO file. To upgrade a MassOS installation, see Upgrading MassOS. To repair a MassOS installation, see Repairing MassOS. To install MassOS manually, see Manual Installation. To build MassOS from source, see Building MassOS.
- 64-bit Intel or AMD CPU.
- 16GB of disk space.
- 2GB of RAM.
- 4GB USB flash drive (for live environment and installer).
- 1024x720 or higher screen resolution.
NOTE: If you intend to install MassOS in a virtual machine (VM), using software such as VMware or VirtualBox, please see the complementary MassOS on Virtual Machines page. This contains detailed information on which VM software is supported, and how to correctly set up and configure the virtual machine for MassOS.
Note that this guide is dedicated to installing newer builds which use the osinstallgui graphical installer, as opposed to the older TUI-based installer. These builds are considered "experimental" and are not yet published as stable releases. However, a link to a server containing them can be found in the changelog.md file in the MassOS repository. In any case, you want to download the file ending with the name .iso, which is the Live ISO image. Do not download the .tar.xz file, as that is the raw rootfs tarball designed for manually installing. The files ending in .b2 are Blake-2 checksum files which can be used to verify your download. Newer experimental builds are also published with a detached GPG signature .asc file - signed by this GPG key, and can be used to verify the integrity of your download as well as (or instead of) the Blake-2 checksum file.
Note that, currently, we only provide experimental builds with the Xfce desktop environment. GNOME is no longer supported, and no further development on it is planned for the forseeable future. This article will no longer contain information about the differences between the two desktop environments unless development for GNOME on MassOS is resumed at any point in the future.
Note also that we now include device firmware by default in MassOS ISO images, and no longer support ISO images without firmware. For more information on the rationale behind this decision, see MassOS and Free Software.
This section will include a tutorial demonstrating how to create a bootable USB flash drive using the ISO file you have just downloaded. Guides are provided for all major operating systems.
For information about other common tools frequently used to create bootable USB flash drives, and why they are discouraged for use with the MassOS ISO, please see the Notes on other bootable USB tools and solutions section below.
The balenaEtcher utility can be used to write the ISO image to a USB flash drive under Windows. Head to the balenaEtcher website, scroll down to the Downloads section, and then select the version for Windows.
To install the application, simply open the EXE file. You may be prompted to run it as administrator. The application will install and start automatically. To run it on subsequent occasions, it will be in your list of applications in the Windows start menu.
First, you must select the downloaded MassOS ISO image (shown by 1). Then, select the USB flash drive you wish to write the image to (shown by 2). Finally, confirm the flash by pressing the Flash! button (shown by 3). Note that, after beginning the flash, you may need to approve an administrator prompt - this is normal/expected behaviour.
Wait patiently while the flash process completes.
After the flash completes, you can close balenaEtcher and disconnect the USB flash drive from the computer. It will now be ready to use - so proceed to Booting the live environment below.
NOTE: While the ISO image can be written to a USB flash drive using any Apple Mac computer, MassOS itself can only be installed on Intel-based Macs. All Macs released after 2020 are based on Apple Silicon instead of Intel, which MassOS cannot be installed onto.
The balenaEtcher utility can be used to write the ISO image to a USB flash drive under macOS. Head to the balenaEtcher website, scroll down to the Downloads section, and then select the appropriate version for your Mac.
NOTE: We recommend downloading from a browser that ISN'T macOS's built-in Safari browser, so as to avoid any possible permission errors when subsequently attempting to install/run the application.
To install the application, open the DMG file and drag the application into your applications folder as instructed.
The balenaEtcher application will now be in your applications list. Find and open it.
First, you must select the downloaded MassOS ISO image (shown by 1). Then, select the USB flash drive you wish to write the image to (shown by 2). Finally, confirm the flash by pressing the Flash! button (shown by 3). Note that, after beginning the flash, you may need to type your user password - this is normal/expected behaviour.
Wait patiently while the flash process completes.
After the flash completes, you can close balenaEtcher and disconnect the USB flash drive from the computer. It will now be ready to use - so proceed to Booting the live environment below.
As described in the guides for Windows and macOS, the balenaEtcher utility can also be used on GNU/Linux, to write an ISO image to a USB flash drive. Head to the balenaEtcher website, scroll down to the Downloads section, and then select the Linux version to download.
Extract the contents of the downloaded ZIP file. The process to do this may differ depending on the desktop environment and archiving utility your system uses. In this example, right-click context menu is sufficient to extract the contents.
Enter the directory containing the extracted files, and double-click on the file named balena-etcher to open the program.
First, you must select the downloaded MassOS ISO image (shown by 1). Then, select the USB flash drive you wish to write the image to (shown by 2). Finally, confirm the flash by pressing the Flash! button (shown by 3).
Note that, after beginning the flash, you may need to type your user password - this is normal/expected behaviour.
Wait patiently while the flash process completes.
After the flash completes, you can close balenaEtcher and disconnect the USB flash drive from the computer. It will now be ready to use - so proceed to Booting the live environment below.
Rufus is a Windows-only program which can be used to write an ISO image to a USB flash drive. While it can be used for MassOS ISO images, you should select DD Image Mode as the writing method, when prompted. It is possible to instead use the mode recommended by Rufus (ISO Image Mode), but this is a Rufus-specific feature that can, under some specific circumstances, cause issues booting the MassOS live environment. By contrast, DD Image Mode is always safe.
The DD Image Mode replicates the behaviour of every other recommended flashing program described in the OS-specific guides above, hence why it's always safe to use. The ISO Image Mode, on the other hand, tries to set up the bootable USB in such a way that you can continue using the volume as a standard USB flash drive, even after the ISO image has been written. It achieves this by copying the files from the ISO image onto a standard FAT32-formatted partition, and then performing some tweaks to make Legacy BIOS boot work (no tweaks are needed for UEFI as the firmware will natively support booting from FAT32 volumes).
For the longest time, the MassOS ISO images did not boot correctly when written using ISO Image Mode. This was caused by our Live CD's boot/kernel parameters being set incorrectly, and was not a bug with Rufus. However, this problem has been fixed as of MassOS experimental-20250816, and ISO Image Mode has now been tested and works correctly. Nonetheless, there are some considerations to keep in mind when using ISO Image Mode:
-
When the drive is writeable and usable as a normal flash drive, even after the MassOS ISO has been written to it, the issue is that you may accidentally delete a file on the drive that is required by the MassOS boot process, which would very likely cause the boot process to fail in an obscure and hard-to-debug way.
-
You may accidentally change the volume label (or Rufus may even do it by itself), which will cause the boot process to fail, as it depends on passing the expected default volume label (
MASSOS_LIVE) as a boot parameter during the boot process (although Windows may show a longer and more descriptive name, due to reading theautorun.inffile, which allows the volume to display in Windows explorer with a name that differs to what it actually is).
Therefore, use Rufus with caution, and preferably choose the DD Image Mode where possible. If you do use ISO Image Mode, be careful not to delete any files that are needed for the Live CD boot process, and do not change the volume label directly (you can, however, modify the autorun.inf file, which Windows uses to display a friendly name in Windows explorer that can differ from the "real" label of the volume itself).
Ventoy is a solution to allow a single USB flash drive to contain multiple bootable ISO images. It has historically been known to cause issues booting the MassOS live environment, however newer MassOS builds have workarounds in place to fix Ventoy compatibility. Nonetheless, there are still specific requirements you must be aware of, and comply with, when using Ventoy to boot a MassOS ISO:
-
You must copy the MassOS ISO directly to the top-level (root) directory of the Ventoy partition. You must NOT put it in a sub-directory.
-
You must NOT change the file name of the ISO file. The file name must be kept exactly as it was when you initially downloaded the ISO file. For example:
massos-<VERSION>-livecd-x86_64-<VARIANT>.iso(obviously<VERSION>and<VARIANT>are placeholders here).
Breaking either of the above two requirements will very likely cause the MassOS live environment to fail to boot under Ventoy. Therefore, you should use Ventoy with caution, and if you are at all in doubt, please consider instead using the OS-specific methods described above to directly write the MassOS ISO image to the USB flash drive.
If you want to use MassOS under Ventoy with UEFI secure boot enabled, you must ensure the Ventoy installation on the drive was configured with secure boot support. This can be done using the drop-down menus found in the Ventoy installation program. Despite the fact that Ventoy itself uses a Microsoft-signed shim bootloader, you will still need to import the MassOS secure boot certificate into your firmware, as described in UEFI Secure Boot, in order to be able to successfully boot the MassOS live environment under UEFI secure boot. This is because, from the firmware's perspective, Ventoy's secure boot support is unrelated to MassOS's secure boot support.
You'll need to restart your computer to be able to boot from your USB flash drive. To boot from the flash drive, you normally have to press a special key during startup (when you see the BIOS logo). This could be any of the following: Escape, F1, F2, F9, F10, F11, F12. If you are unsure, consult the manual for your system. If done successfully, MassOS will either immediatey start up from your USB flash drive, or the system will show a boot menu allowing you to boot from the flash drive.
NOTE: If you are using UEFI and the boot fails with a Secure Boot Violation or Security Violation error, then you will need to either disable secure boot in your system's firmware settings, or import the MassOS secure boot key into your firmware, if supported. Please see UEFI Secure Boot for more information on this, and instructions on how to do this process.
You should be shown a bootloader menu with several different boot options for MassOS. In most cases, you will want the first entry, labelled MassOS Live CD. However, you may want one of the other entries, depending on your system configuration:
- Copy-to-RAM - Choose this option if your machine has 4GB or more system RAM, and you are willing to wait several minutes for the live environment to boot up. This allows the live environment to be copied to the system RAM and therefore run entirely from it, thus allowing you to disconnect the USB flash drive after the system has booted, and all programs (including the installer) will still work properly. By contrast, if you use the default option, which doesn't copy to RAM, then the bootup time is shorter, but you must keep the USB flash drive connected to the system for the entire duration of you being booted into the live environment, including when running the installer. If your system is capable of using this option, and you are patient enough to wait out the prolonged boot time, then we recommend it.
-
Fallback graphics - This is a debugging option, useful only if you encouter a black screen after startup of the live environment, indicating your GPU is unsupported by MassOS. This will force the system to disable all graphics acceleration and rely only on a basic framebuffer driver which should be able to output video on any GPU, even unsupported ones. This option is equivalent to simply adding the kernel command-line parameter
nomodeset. - Copy-to-RAM + fallback graphics - This should be self-explanatory - it is a combination of the previous two options.
All the other options are not used to boot the MassOS Live CD - rather, they are general useful options to have on a bootable USB flash drive for a variety of purposes unrelated to MassOS. The MassOS Live CD includes them with the goal of providing convenience.
After the live system has booted, you'll be shown a welcome screen like this:
This shows some of the key features in MassOS and how to navigate the OS.
You may freely use the live system to try out MassOS and see if it is right for you before you decide to install it. You do not need to proceed with the installation, as described below, until you are ready and willing to.
- Launch the installation program found on the desktop to begin the installation of MassOS. If you get any sort of "Untrusted Executable" warning, simply select "Mark Executable" or "Launch Anyway" and continue.
- Choose "Install" to start the installation.
- Proceed through the setup pages, where you will be prompted to select your desired locale, keymap, timezone, username, password and system hostname. You can use this as an opportunity to customise the system to your needs.
- Choose which disk you want to use for the installation. It must differ from the USB flash drive you used to create the bootable live environment.
- Choose how you want to set up the disk. Option 1 will erase the whole disk and install MassOS. Option 2 will let you choose a partition to install MassOS on (for dual-booting). Option 3 will let you manually create and modify partitions. If you choose option 2, you will be shown a list of the partitions already on the disk, and prompted to select the one you wish to use for the installation of MassOS.
- You may be asked whether or not you wish to use the btrfs filesystem instead of ext4. Unless you know of a reason why you don't want that, you should answer "Yes" here.
- You will be asked whether or not you want a swap space to be added. Swap functions as an emergency RAM backup on the disk in case the system runs out of memory. It is NOT a RAM substitute. If you have 8GB or less system RAM, or you intend to run memory-heavy applications, then swap is advisable. If you are highly memory-constrained and have less than 4GB of RAM, you are strongly recommended to make use of swap space. Otherwise, you may not need it.
- You will be given a final confirmation warning before the installation starts. Answer "Yes" to continue.
- The installation process should only take a few minutes to complete. Be patient and do NOT close the dialog box during this process!
- After the installation completes, the system will be automatically configured as necessary. This may take a while. An initramfs also has to be generated during this stage, which is required to boot the system. So be patient while this takes place, and again, do NOT close the dialog box! Also be aware that it is normal for the progress bar to remain at 0% and not make any visual progress. This is normal behaviour, due to the fact that it is not possible to capture a progress report of this stage. So again, just be patient.
- If your system is booted in UEFI mode, you will be asked whether you are installing MassOS to an internal or a removable disk. Unless you are making a portable installation on a removable drive, you should select the "Internal" option, which is the default. For more information about this, as well as the rationale behind why this option is included in the installer, please read this section in the osinstallgui FAQ.
- After completing the installation, this message will be shown, and you will be given the option to either shut down the system now, to allow you to boot into your new installation immediately, or continue testing the live environment before rebooting into your new installation.
Remember that you must unplug the USB flash drive before attempting to boot the system again, so as to ensure you boot into your new installation, instead of accidentally restarting the live environment.
For general information on how to make the most out of your new installation, have a look at Post Installation. It contains information on how to do things like install software, customise your desktop, amongst other useful tips.