Serpantinum: a QML shell for Hyprland, Niri, Sway and Mango that stopped being dotfiles in v2

Moving from v1 leaves your compositor settings behind

Serpantinum began as a set of dotfiles and is now a shell. That shift has a direct cost for anyone upgrading from v1. All previous configuration is backed up and left unused, and settings that belong to the compositor, such as monitors, keybinds and autostart, are now the user's responsibility.

In practice, after the upgrade your shell comes up but the compositor no longer carries the monitor layout, shortcuts or startup programs that v1 managed. You need to rebuild those in your compositor's own configuration, using the v1 backup as a reference. Plan the upgrade for a time when you can sit at the machine and fix a wrong monitor arrangement by hand.

One installer script for pacman, dnf and xbps

On Arch-based distributions, including systemd, OpenRC and other init systems, on Fedora-based ones such as Nobara and Ultramarine, and on Void Linux with glibc or musl, installation is a script that detects the distribution and uses pacman, dnf or xbps:

curl -fsSL install.serpantinum.dev | bash

If that fails, the fallback fetches the script straight from the repository's master branch:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/ilyamiro/serpantinum/master/install/install.sh)"

Both pipe remote code into bash, so read install/install.sh in the repository first if that matters to you. The script only knows those three package managers. On a distribution outside the Arch, Fedora and Void families there is no scripted path, and you are left with the guides at serpantinum.dev.

Updates mean running the installer again

There is no separate update command. When Serpantinum notifies you that a new version is available, you run the same install script again and choose update. Releases come fast: v2.3.1 on 2026-10-30, v2.3.2 on 2026-10-31 and v2.3.3 on 2026-11-02, and the last push to master was on 2026-11-03, so the project is under active development.

That pace means the update prompt will appear often, and each time the answer is another run of a remote script, which is a step to fit into how you manage the machine. CHANGELOG.md in the repository is where to check what changed before you accept one.

NixOS uses a flake and modules instead of the script

NixOS is handled separately. The repository carries flake.nix, flake.lock, default.nix and a nix/ directory, and the NixOS installation guide at serpantinum.dev/installation/nixos covers the flake setup, the NixOS and Home Manager modules, and updating. The curl script is not the route on NixOS.

The consequence is that NixOS users update through their flake rather than by rerunning the installer, and the module options on the website are the reference for what can be declared. Anyone mixing a NixOS system with the script-based notes should follow the NixOS guide only.

serpantinum-audio takes over from EasyEffects

The equalizer, balance, mono, channel swap, dynamic range modes and dynamic EQ do not run on EasyEffects. They run on serpantinum-audio, a separate small PipeWire processor from the same author that replaces EasyEffects. The installer and the packages install it, and on the first start after updating, Serpantinum hands your audio over from EasyEffects.

If you have tuned EasyEffects presets or use it for other processing, that handover changes your audio path the first time the updated shell starts. Read the audio engine guide at serpantinum.dev/audio before updating, so you know what replaces each setting you rely on.

Compositor support pulls in third-party repositories

Four compositors are supported: Hyprland, Niri, Sway and Mango. The installer detects the running compositor and deploys configuration for it, so run it from inside the session you intend to use.

Two combinations depend on repositories outside the distribution. On Fedora, Mango comes from the Terra repository. On Void Linux, Hyprland comes from the third-party black-hole.dev repository. Choosing those combinations adds a package source you have to trust and keep enabled. If your policy forbids extra repositories, pick one of the other supported compositors on those distributions.

Starting the shell and where configuration lives

Once installed, the shell is launched with a single command:

serpantinumd start

Configuration is covered by the configuration guide at serpantinum.dev/configure rather than in the repository front page. The code itself is QML, with src/, config/, bin/ and packaging/ at the top level plus docs/ and website/ directories.

The project is licensed under the GNU Affero General Public License version 3 or any later version, copyright Illia Miroshnichenko. If you fork the shell and distribute a modified build, the AGPL terms apply to your changes. A material SDDM theme credit goes to Darkall44/Qylock.

Editorial conclusion

Serpantinum suits users on Arch, Fedora or Void derivatives, or NixOS, who run Hyprland, Niri, Sway or Mango and want a ready shell instead of assembling one. It is a poor fit if you depend on EasyEffects, cannot use the third-party Terra or black-hole.dev repositories where your compositor needs them, or are upgrading from v1 without time to rebuild monitor, keybind and autostart settings. Check the migration notes and the audio handover before updating, and expect several releases a week.

Frequently asked questions

Official sources

1. ilyamiro/serpantinum on GitHub
2. Issues
3. License: AGPL-3.0
4. README