Repository navigation
elementaryOS "Atomic" basic guide
Work-in-progress guide for contributors and technical users. Not made for end users
To build elementaryOS locally, you need the following runtime dependencies:
- podman
- just
- fzf (optional)
- zstd
First start by creating local signing keys with just regenkey
To start a build, run just do-daily to start a build based on the daily ppa, or just do-stabe to start a stable ppa build.
This should take between 20 and 30 minutes, following builds will be faster.
It will result in a bootable iso.
Local builds CANNOT use elementaryOS features, to test out a new feature make a PR, an ISO will be built by the CI/CD.
elementaryOS atomic uses a bunch of new technologies you might never have heard from before.
| Program | Use | Docs |
|---|---|---|
| mkosi | Builds the OS image itself, the parition layout and signing keys | https://github.com/systemd/mkosi/blob/main/mkosi/resources/man/mkosi.1.md |
| repart | Used to install OS images to disk at runtime or inspect them | https://www.freedesktop.org/software/systemd/man/latest/systemd-repart.html |
| sysupdate | Updates your system | https://www.freedesktop.org/software/systemd/man/latest/systemd-sysupdate.html |
| updatectl | User-friendly CLI to sysupdate, also let's you enable features | https://www.freedesktop.org/software/systemd/man/latest/repart.d.html |
| sysexts | Overlay over /usr, letting you modify /usr at runtime, without actually changing it | https://www.freedesktop.org/software/systemd/man/latest/systemd-sysext.html |
| erofs | True read-only filessysext with verity, used for /usr | https://docs.kernel.org/filesystems/erofs.html |
| tmpfiles/factory | Tmpfiles let's you copy/link configs at runtime so they stay in sync with the expected image | https://www.freedesktop.org/software/systemd/man/latest/tmpfiles.d.html# |
sudo sysupdate list
sudo updatectl update or sudo sysupdate update
- Get available release tag
sudo sysupdate list, copy the full image version string - Update
sudo sysupdate update {IMAGE_VERSION}
The recommended way to install software is via AppCenter and Flatpak. Simply open AppCenter, and install your apps! AppCenter and Flathub are enabled by default
CLI package managers on elementaryOS are WIP, but you can use the following:
Snaps are removed, not supported and cannot be installed
Vanilla NixPkgs does works, but is not tested, supported or recommended. This is only here so no ones asks.
AppImages are not supported.
"Modern" AppImages using fuse3 will work like on any other distro. Legacy type2 AppImage will usually not work at all.
To run VMs, you have three options:
The virt-manager flatpak is really easy to install, but is limited:
- No host network (session networking)
- USB and devices passthrough can be problematic without custom udev/polkit rules
Install (flathub):
flatpak install org.virt_manager.virt_manager org.virt_manager.virt_manager.Extension.Qemu
If no qemu sessions show up in virt-manager, run
flatpak run org.virt_manager.virt-manager -c "qemu:///session" --show-host-summary
and check Autoconnect
Gnome Boxes is available on flathub: https://flathub.org/en/apps/org.gnome.Boxes
The extension only comes with the services and cli tool. Install virt-manager (GUI only) from flatpak, and connect it to the extension qemu.
This has all qemu fonctionalities
To see available features, run : sudo sysupdate features
- Features starting with
ext-are extra optional packages - Features starting with
driver-are out-of-tree kernel modules
To enable one, run sudo updatectl enable --now {full-feature-name}
Then reboot.
Once enable, the feature will auto-update with the base system
- ext-virt : Qemu and virt-related packages
- ext-devel : Packages required to develop elementaryOS itself, also include make, ninja and common build tools
- driver-nvidia : Nvidia-open driver from Ubuntu Restricted
- driver-broadcom: WL driver from Ubuntu Restricted
Directly after running sudo updatectl enable --now {feature}, run sudo systemctl status systemd-sysupdated.
There should be a clear error
Requires a full disk to be wiped, same disk dual boot is not supported
- UEFI only
- 4gb ram minimum
- 45gb disk mimimum
- SSD (recommended)
- TPM2 (optional)
- SecureBoot (optional)
For flashing, an USB3 is highly recommended, USB2 will work, but will take quite a long time. The USB drive must be at least 8GB, and flashed with a standard flashing app (no Ventoy or similar). Impression is well tested with elementaryOS atomic. Others, like BalenaEtcher, FedoraWriter and many more should also work.
- Nvidia-Open (Only for modern-ish GPUs, see compatible GPUs list)
- Broadcom wifi
This is incomplete and untested, help wanted Check this for now: https://gitlab.gnome.org/GNOME/gnome-build-meta/-/snippets/7081
In systemd-boot, press e to edit the current entry, and add the systemd.mask=systemd-sysext.service option
Enabling an usroverlay can be usefull for testing configurations or software than must be installed in /usr. This may result in catastrophic failures, use at your own risk.
Create a mutable overlay:
You can also make it persist across reboot by creating /var/lib/extensions.mutable/usr instead
sudo systemd-sysext unmerge
sudo mkdir -p /run/extensions.mutable/usr
sudo systemd-sysext merge --mutable=yes
You can now add/modify files in /usr, they are stored in /var/lib/extensions.mutable/usr.
Delete that overlay (and all it's data):
sudo rm -rf /var/lib/extensions.mutable/
sudo systemd-sysext refresh
This is to switch between daily, proposed and stable This is not recommended outside of debugging
While you can switch to daily images with this method, please still consider sponsoring elementary so we can keep making them!
- Get a root shell
run0
- Set your new variant (daily, proposed or stable)
NEW_STREAM=stable
cp /etc/os-release /tmp/os-release
sed -i "s/^VARIANT_ID=.*/VARIANT_ID=${NEW_STREAM}/" /tmp/os-release
- Update to the new variant
SYSTEMD_OS_RELEASE=/tmp/os-release sysupdate update
https://secureblue.dev/faq#immutable
https://0pointer.net/blog/fitting-everything-together.html
- GnomeOS; Has a similar update mechanism, but build with buildstream, without mkosi
- KDELinux; Built from ArchLinux with mkosi
- Nuraeco's Duranium; Build from nura with mkosi
- Zirconium; Really similar to elementaryOS, but from Fedora
See the wiki sidebar (below on mobile) for other sections, sub-pages, etc.