The manual

One line, and it works.

• A single command: curl the install.sh and you're done. Nothing to clone, no packages to pick by hand, nothing to fix afterwards.
• It detects your distribution — Arch, NixOS, openSUSE, Fedora, Debian, Ubuntu, or Alpine —, checks for sudo authentication and network connectivity before touching anything.
• --preview runs the whole script through without executing a single line.
• --resume picks up an interrupted install: finished steps are skipped, and configs that already match the repo are left alone instead of being backed up and overwritten.
• The log goes to a file and it says where, so a failure isn't lost in the terminal.

Every flag

16 flags, read from install.sh --help. The README only lists 12 of them.

79 keybindings, parsed from hyprland.lua on v0.29-2-g777e9ec. Read from the repository, not from a running compositor, so this is the list a fresh install gets.

Two panels, and the login screen only on one of them.

• The machine has two: the built-in panel and an external one over DP. Each carries its own name, resolution and scale in the compositor's configuration, and the built-in one is the primary.
• That is why the login screen only ever appears on the internal panel: the external one is not a login target. It is a screen, not a door.
• The wallpaper daemon needs to know which one it is painting, and it reads that from the environment. If the variable is missing it falls back to wayland-0, finds nothing there, and paints zero screens without saying anything. It is the quietest failure in the whole setup.

Compositor

Hyprland with official plugins

Dynamic island

Quickshell (Qt6 QML with IPC)

Dock

Rust-Dock (GTK4 + gtk4-layer-shell)

Status bar

Waybar with Pywal colors

Terminal

Kitty

Shell

Zsh with syntax highlighting and autosuggestions

Launcher

Rofi with Pywal themes

Lockscreen

Hyprlock + Hypridle

File manager

Thunar + Plugins & Tumbler

Theming

Pywal (System-wide dynamic color synchronization)

Wallpaper engine

awww for static plus mpvpaper for animated gif, webp and mp4

System CLI

rhythm unified command with 11 groups

Updates

OTA updater with migrations and pre-update snapshots

Audio

Pipewire + Wireplumber

Display manager

SDDM astronaut theme with Pywal hook

AUR helper

yay

16 components, read from the README.

The strip on the top edge. Quickshell, and every part of it is a plugin.

• The strip that sits against the top edge of the screen. It folds down to 34 px and opens when it has something to show: a track changing, a network going down, or a notification arriving. Reaching the edge with the mouse brings it out as well.
• Spaces overview: macOS Mission Control-style desktop switcher with live double-buffered workspace previews, running app chips, and interactive navigation.
• Corner System Monitor: real-time hardware telemetry and htop metrics with concave spring-physics wings, multi-core CPU sparklines, and GPU profile switching.
• Public Wi-Fi captive portal: automatic network connectivity probing that detects captive portals and renders a direct one-click browser login card.
• Battery diagnostics: multi-battery laptop architecture telemetry (BAT0 + BAT1) with adaptive charging glyphs and real-time health panels.
• Nothing inside it is privileged. The clock, the launcher, the control centre, and the screen capture tool are all plugins loaded in declarative QML, and any of them can be tweaked without breaking the rest.
• SUPER + I folds it by hand, which is the quickest way to check whether it is doing something.

The strip along the bottom edge. Ours, in Rust and GTK4, compiled during the install.

• A dock in Rust with a GTK4 interface, compiled from source by the installer. There is no package to install and nothing to update afterwards. --skip-rust-dock skips the build if you would rather put something else there.
• It has two halves. The left one holds the applications you have anchored; the right one fills with whatever else is open. Windows appear and disappear in real time at 30 fps, because the dock asks the compositor instead of guessing.
• Drag an icon to reorder it. Hover a window for a preview rendered with grim. Clicking focuses, clicking again minimizes.
• It takes its own options from the command line: position, icon size, padding, spacing, corner radius, opacity, which monitor to appear on, and --smart-view, which keeps it hidden until the cursor reaches the edge.
• What it does not do: no clock, no tray, no systray, no favourites launcher. The clock is in the bar, and the launcher is SUPER + A. Looking for a panel with all of that in one piece, this is not it.

The status bar at the top of the screen. Powered natively by Quickshell in reactive QML (with legacy Waybar support), styled to match the active Pywal wallpaper palette automatically.

Configuration

Quickshell top bar lives in ~/.config/quickshell/waybar-island/ and is built in declarative QML. Legacy Waybar configuration remains available in ~/.config/waybar/.

The wallpaper decides the colours, and everything else follows.

• Change the wallpaper and pywal writes a new palette from it. The bar, the dock, the launchers, the terminal and the island all recolour themselves. There is no theme picker and no second colour choice to make anywhere.
• It reaches further than it looks. The terminal colours, the GTK theme behind the dialogs, the cursor and the login screen's own template all come from the same sixteen values. One wallpaper moves all of it.
• The wallpaper also repairs itself: if a monitor stops being painted, it is repainted within seconds, without asking and without a restart.
• What it does not do: understand a photograph. pywal samples the image and picks from what it finds, so a wallpaper with three competing colours gives a correct palette that is not always the one you would have chosen.
• And the fade only runs on the built-in panel. On the external one the wallpaper cuts instead of dissolving, because that screen is driven differently and nobody wired the animation into it.

The palette

Sixteen colours, read out of the wallpaper.

• pywal turns the wallpaper into a palette of sixteen colours and writes them to ~/.cache/wal/colors.json. The bar, the dock, the launchers, the terminal and the island all read that file instead of carrying colours of their own.
• The file is rewritten every time the wallpaper changes, so there is nothing to configure and nothing to keep in sync. The installer sets it up once and it looks after itself from then on.
• What it does not do: choose well on a busy picture. It samples the image and picks, so a wallpaper with three competing colours produces a palette that is correct and not always pretty.

SDDM, with its own theme, and only on the built-in panel.

• A custom theme for SDDM, using the system cursor and the wallpaper you already have, so the screen you log in from is the same picture you get afterwards.
• The files it needs live in /etc, which is not somewhere a normal user writes, so they are deployed by rhythm-sddm-deploy rather than installed directly. That script is the single source of truth for them: when it runs it rebuilds every file from the repository.
• pywal rewrites the theme's colours while the machine is running, which is why those files are not versioned. Running the deploy script brings them back to the repository's version; running it twice is harmless.
• It only comes up on the internal panel. There is no way to log in from the external one, and that is not a setting somebody forgot: the external screen is never a login target.
• What it does not do: work on a machine with a single panel. The theme assumes the built-in display exists, and on a laptop with the lid closed at boot there is nothing to draw it on.

It says what is broken instead of failing quietly.

• One command that looks at the whole machine and says what is missing or wrong. Without it a problem shows up three weeks later and nobody knows where it came from.
• The installer runs it when it finishes, and the update runs it at the end too, so there is nothing to remember and nothing to schedule.
• It only reads. It does not fix anything, it does not install anything, and it will not touch a file: the fix is printed next to the finding, for you to run.
• The block below is a real run of it on a machine where nothing is wrong, with the colour codes taken out because they mean nothing on a web page. When something is wrong it fails in the same place, with the command that fixes it underneath.

rhythm-doctor: check (repo: ~/hyprland)   ok    /etc/sddm/Xsetup is up to date  ok    xsetup.conf.disabled is present (X11 stays off, correct)  ok    all deployed units point at real executables  ok    scripts referenced by the units are present  SDDM greeter:    wrapper: correct    template: correct    sddm.conf: correct    login cursor: correct    theme: correct    Xsetup (X11 fallback): correct    cursor theme 'Bibata-Modern-Ice' is installed    OK  ok    battery-limit.conf in ~/.local/state  ok    no local edits in .config/hypr doctor: everything correct.

The installer is not a one-shot script. There is a second half to it: the update, the overlays, and what happens to the files you have edited.

Your edits survive updates

Updating used to overwrite anything you had edited in ~/.config, leaving a dated .bak beside it. Two trees exist now: the base is re-laid in full on every update, and your edits live in a sparse overlay applied last, so they win without opting out of upstream fixes.

Real installations tested and verified across every supported Linux distribution. The installer detects your package manager and kernel environment automatically.

CachyOS

pacman / paru

Arch-based (Bore / Linux-cachyos kernel)

High-performance Arch derivative with optimized x86-64-v3/v4 binaries. Full hardware acceleration, dynamic Pywal color integration, and native compositor support out of the box.

Debian

apt

Debian 13 (Trixie) & 12 (Bookworm)

Stable and testing releases supported. Includes targeted QML6 declarative dependencies, PAM configuration, custom Astronaut SDDM session handoff, and Wayland compositor integration.

Fedora

dnf

Fedora 40 & 41 (Workstation / Server)

Modern Red Hat base with PipeWire audio, systemd user services, and SELinux-aware wrappers. Waybar, Quickshell, and full font stack installed and themed automatically.

NixOS

nix / flake

NixOS 24.05 & Unstable

Declarative and reproducible installation. Integrates rust-dock placement, standalone quickshell components, Pywal color generation, and complete Wayland environment.

openSUSE

zypper

Tumbleweed, Slowroll & Leap

Rolling and stable openSUSE branches. Resolves pywal color scheme transitions, colors-rofi-dark integration, SUPER+Shift+W wallpaper toggles, and Waybar monitoring.

Ubuntu

apt

Ubuntu 24.04 LTS & 24.10

Canonical LTS platform support. Handles Wayland compositor dependencies, audio/brightness keybindings, SDDM login screen setup, and cliphist clipboard daemon.

6 distribution families captured and validated with live testing builds.

The repository is mostly a pile of scripts with nothing to compile, which is why installing it takes one command and not a build system. Almost all of it lands in ~/.local/bin, which is already on your PATH, so a script is installed by being copied and made executable.

The files that are not yours are the ones under /etc and /usr: the login screen has to be written as root, so those go in a directory under sddm/ and a deploy script copies them into place. Editing them by hand works until the next update, which puts them back.

Counted from the repository, hiding dotfiles and __pycache__. Listing all 134 scripts would be a table nobody reads top to bottom.

Start here before changing anything. Most of what looks broken is one file that drifted, and rhythm-doctor usually says which.

Where the logs are

An interactive timeline tracking shipped capabilities, our current active status, and planned developments for upcoming releases.

Scroll through the roadmap to trace completed milestones up to the current release and into future planned features.