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 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
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.