Caelestia Shell: Complete Guide, Installation and Configuration

Caelestia Shell is a Quickshell-based desktop shell for Hyprland that replaces Waybar, your app launcher, notification daemon and lock screen with a single animated, wallpaper-themed interface. It's one of the most starred Hyprland ricing projects on GitHub right now, and search interest for it spiked hard in August 2026.

This guide covers what Caelestia actually is (and how it differs from "Caelestia dots"), every real installation method, how its configuration system actually works under the hood, an honest comparison against the other Quickshell and Wayland shells people mention in the same breath, and the errors you're most likely to hit.

What Is Caelestia Shell?

Caelestia Shell is a desktop shell built with Quickshell, a Qt6/QML widget framework for Wayland, designed specifically to run on top of Hyprland. The project describes itself as "a fluid, morphing shell for your Linux desktop," and that's a fair summary: instead of running Waybar, a separate launcher like Rofi or Walker, a notification daemon like Dunst or SwayNC, and a lock screen like Hyprlock as four independent processes with four separate configs, Caelestia bundles all of it into one animated, cohesive interface.

The project is open source under the GPL-3.0 license and, as of this guide, sits at 12.6k stars and 916 forks on GitHub, which is a genuinely large community for a shell-only ricing project, most Hyprland bars top out in the low thousands.

What it actually does for you, module by module:

The defining feature is its color system: Caelestia generates an accent palette directly from your active wallpaper, Material You style, and pushes it through every module at once. Change your wallpaper, the bar, launcher, notifications and lock screen all re-theme together.

A couple of the modules go further than a typical status bar bundle. The lock screen isn't just a themed overlay, it supports fingerprint unlock through Fprint and face unlock through Howdy where your hardware and system configuration support them, on top of the usual password fallback. The dashboard pulls current media playback, system performance and local weather into one slide-down panel instead of scattering them across separate widgets, which is closer to what a phone's quick-settings panel does than what most desktop status bars attempt.

Caelestia Shell vs "Caelestia Dots": Two Different Things

This is where a lot of the confusion in search results comes from, and it's worth clearing up before you install anything.

• caelestia-dots/shell is the shell itself: the Quickshell component covered in this guide. You can install it on top of any Hyprland setup you already have, and it works standalone.
• caelestia-dots/caelestia (informally "Caelestia dots") is the full dotfiles collection: Hyprland config, Fish shell setup, keybindings and theming, wrapped in an automated installer script that sets up the shell and the rest of your desktop from a fresh Arch install.

If you already have a working Hyprland setup and just want the shell, install caelestia-shell directly (see below). If you're starting from a bare Arch install and want the whole opinionated desktop, the automated installer from caelestia-dots/caelestia is the faster path, it handles dependencies, login manager and Hyprland config for you.

This distinction matters most if you're migrating from another rice. If you already have Hyprland keybindings, a Fish config, or window rules you've spent time tuning, running the full "Caelestia dots" installer will overwrite them, it's designed to set up a complete desktop, not to slot the shell into an existing one politely. In that case, install caelestia-shell on its own and keep your existing Hyprland config untouched, you just add the exec-once line that starts the shell (covered below) rather than adopting the whole opinionated setup.

Requirements Before You Install

Caelestia Shell only runs on Hyprland. It won't work on GNOME, KDE Plasma, Sway or any other compositor, that's a hard requirement, not a recommendation.

Officially packaged and supported on:

• Arch Linux (and Arch-based distros with AUR access), via yay or paru
• NixOS, via flakes

Manual compilation with CMake can technically get it running on other Wayland distros that ship Hyprland and Quickshell, but the project only tests and packages for the two above, so treat anything else as unsupported.

Runtime dependencies: glibc, gcc-libs, Qt6 (base, declarative, imageformats), Material Symbols font, NetworkManager, PipeWire, brightnessctl, ddcutil, libcava, aubio, libqalculate, power-profiles-daemon, swappy, fish, bash.

Build dependencies (only if compiling manually): cmake, ninja, qt6-shadertools.

That's a long dependency list, and it's part of the real cost of running Caelestia: pulling in PipeWire, NetworkManager, a calculator library and an audio-visualizer library just for a shell is heavier than Waybar's near-zero footprint. Independent testing puts Caelestia's idle RAM usage around 1.5 GB, driven mostly by its animations, so budget for that on lower-spec hardware.

GPU: no specific GPU is required beyond what Hyprland itself needs to run, testing across both AMD and NVIDIA setups reports it working fine on either, the animations are handled through Quickshell's own rendering rather than anything vendor-specific. If your GPU already runs Hyprland smoothly, it'll run Caelestia's animations too, the shell isn't the bottleneck on modern hardware, it's the extra idle RAM that matters more on constrained systems like older laptops or low-memory VMs.

How to Install Caelestia Shell

There are four real installation paths, pick based on your distro and how much of your setup you want automated.

Method 1: Arch Linux via AUR (recommended for most people)

1. Make sure you have an AUR helper. If you don't have yay or paru yet, install one first, Caelestia pulls several of its dependencies straight from the AUR.
2. Install the package. For most users:

   yay -S caelestia-shell caelestia-cli

   The shell and the CLI are two separate AUR packages, not a single combined one: caelestia-shell and caelestia-cli. The shell alone does not give you the CLI, and the CLI is what you use to start, restart and control the shell (wallpapers, color schemes, MPRIS). Skipping it is the single most common setup mistake people report.

3. Pick stable or bleeding edge. caelestia-shell and caelestia-cli track the stable release. caelestia-shell-git and caelestia-cli-git build from the latest commit and are genuinely unstable, real reports describe the shell's git package "occasionally breaking during updates." Stick to the stable packages unless you're specifically testing unreleased features.
4. Start the shell (see the section below).

Method 2: The automated "Caelestia dots" installer

If you want the full opinionated desktop (Hyprland config, Fish, theming, login manager) and not just the shell component, run the installer from the caelestia-dots/caelestia repository. It handles:

• Installing dependencies (git, fish, Firefox, Bluetooth stack, SDDM)
• Configuring the login manager
• Setting an initial wallpaper and color scheme
• Adjusting terminal font size
• Writing Hyprland keybindings

This is the faster route on a fresh Arch install, but it will overwrite parts of an existing Hyprland config, don't run it on a desktop you've already customized without backing up your dotfiles first.

Method 3: NixOS via flakes

NixOS support is official, through Nix flakes. You can either run it directly with nix run, or bring it into your system configuration and manage it declaratively with programs.caelestia.settings, which lets you set every shell.json value through Nix instead of hand-editing JSON. If you're already on NixOS, this is the cleanest integration of the three methods, since your shell config lives in the same flake as the rest of your system.

Method 4: Manual build from source (any Hyprland + Quickshell system)

Unsupported officially, but works if you're on a distro without AUR or Nix access:

mkdir -p ~/.config/quickshell/caelestia
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/ -DINSTALL_QSCONFDIR="$HOME/.config/quickshell/caelestia"
cmake --build build
sudo cmake --install build
sudo chown -R $USER ~/.config/quickshell/caelestia

If you plan to customize the shell's actual QML source later, use this manual method from the start. The project's own guidance is explicit: don't edit the files an AUR package installs directly, changes get wiped on the next update. Fork the repo, run it live with qs -p shell.qml to preview changes, then install your fork instead.

A rough sense of the time cost: independent testing of a full fresh-install run (dependencies plus compilation) puts it at 30 to 50 minutes, and around 11.9 GB of disk space on a minimal Arch base once every dependency is pulled in. That's a heavier lift than swapping a Waybar config, budget accordingly.

Do You Need a Login Manager?

Caelestia doesn't require a specific login manager, you can launch Hyprland from a TTY with a shell script if that's your current setup. But if you're installing from scratch, both the manual guide and the automated installer treat SDDM as the default recommendation, mainly because it themes reasonably well alongside a Quickshell-based desktop and has solid Wayland session support.

If you already run GDM or another display manager and it launches Hyprland correctly, there's no need to switch just for Caelestia, the shell itself starts the same way regardless of what put you into your Hyprland session (via exec-once in hyprland.conf, see the autostart fix in the troubleshooting section below).

Starting and Controlling the Shell

Once installed, start it with either:

caelestia shell -d

or, if you don't have the CLI installed:

qs -c caelestia -n -d

The -d flag keeps the shell detached from your terminal so it doesn't die when you close the window it launched from.

If you installed caelestia-cli alongside the shell, you also get IPC control through caelestia shell subcommands: switching MPRIS players, changing wallpapers, and swapping color schemes without editing config files or restarting the shell.

How to Configure Caelestia Shell

This is the part most existing guides skip, because it requires reading the shell's actual source rather than just following install steps.

Config file location: ~/.config/caelestia/shell.json. This file does not exist by default, you create it yourself. Any property you leave out simply falls back to its built-in default, so you never need a complete config, just the values you want to override.

Advanced tokens: ~/.config/caelestia/shell-tokens.json holds lower-level styling tokens for users who want finer control over the generated color scheme than the standard config exposes.

Config subsystems. The shell's settings are split into separate objects, each backing a different part of the interface:

How saving actually works: changing a config value doesn't write to disk instantly. The shell watches for changes and commits them to shell.json after a 500ms debounce, this is why rapid consecutive changes (like dragging a slider) don't thrash your disk with writes, but also why a config edit made externally while the shell is running can get overwritten if the shell itself was mid-change.

Per-monitor overrides. You can override most settings on a specific display by creating ~/.config/caelestia/monitors/<screen-name>/shell.json, using the exact output name Hyprland reports for that monitor. Values set there take priority over the global config, on that monitor only. One caveat worth knowing: a handful of properties are marked as global-only internally and will silently ignore anything you set in a per-monitor override, if a setting doesn't seem to apply per-monitor no matter what you try, that's likely why.

What a minimal override actually looks like. You never need to redeclare the whole config, just the subsystem and the specific keys you're changing. Using only the property names confirmed above:

{
  "bar": {
    "clock": { "format": "HH:mm" },
    "workspaces": { "shown": 5 }
  },
  "general": {
    "apps": { "terminal": "foot", "explorer": "nautilus" }
  },
  "services": {
    "weatherLocation": "Girona, ES",
    "useFahrenheit": false,
    "maxVolume": 100
  }
}

Every key left out, launcher and session behavior, notification grouping, the exact bar entry order, keeps whatever the shell ships as its default. This is also why two Caelestia setups you see in screenshots or ricing threads can look wildly different from a config file that's only 15 lines long, most of the visual identity comes from the wallpaper-driven color scheme, not from shell.json itself.

Customizing Caelestia's QML Modules

shell.json covers behavior and data, it doesn't let you redesign the layout or add new widgets, that requires editing the shell's actual QML source under modules/ (bar, launcher, dashboard, lock, notifications, sidebar, osd, and a few shared utility modules).

The project's own guidance on this is specific: if you installed via the AUR, do not edit the files the package puts on disk, they live in a system path and get overwritten on the next update. The workflow people actually use instead:

1. Fork the caelestia-dots/shell repository.
2. Clone your fork and run it live for previewing changes without a full reinstall: qs -p shell.qml.
3. Edit the QML modules in your fork and watch the change reflect immediately in the running preview.
4. Once you're happy with a change, copy it into your real install location (/etc/xdg/quickshell/caelestia/ for a system-wide install, or your ~/.config/quickshell/caelestia build) so it survives normal usage.

This is meaningfully more involved than editing a Waybar JSON config or a CSS file, QML is a real UI programming language, not a settings format, which is the trade-off behind Caelestia's "harder to customize than Waybar" reputation mentioned in the comparison table below.

How to Update Caelestia Shell

Update method depends on how you installed it:

• AUR (caelestia-shell + caelestia-cli, or their -git equivalents): update through your AUR helper like any other package, yay -Syu or paru -Syu. If you're on the -git package, expect this to occasionally pull a breaking change, that's the trade-off of tracking the latest commit instead of a tagged release.
• NixOS: update through your normal flake update flow (nix flake update on the input, then rebuild your system generation), the same as any other flake-managed package.
• Manual build: pull the latest commit in your cloned repo, re-run the CMake build and install steps from the manual method above.

If you customized QML modules directly per the section above, keep in mind an update can conflict with your changes, that's another reason to keep your customizations in a fork rather than editing installed files in place, forks merge cleanly against upstream, ad hoc edits to installed files just get silently wiped.

Changing the Wallpaper and Color Scheme

Caelestia's headline feature is generating its color scheme from whatever wallpaper is active, so changing the look of the whole shell is normally a one-step action: set a new wallpaper through the launcher's built-in wallpaper picker, or via the CLI (caelestia shell subcommands if you installed caelestia-cli alongside the shell), and every themed module updates together.

If the scheme doesn't refresh after a wallpaper change, that's one of the most-reported issues (see the troubleshooting section below), and it's almost always tied to the color-generation service, not the wallpaper picker itself.

Caelestia Shell vs Other Hyprland Shells

Caelestia isn't the only Quickshell-based option, and it isn't the lightest one either. Here's how it actually stacks up against what else you'll see mentioned for Hyprland:

If you're coming from End-4's dotfiles and found them too heavy, Caelestia is the direct answer: same Material You visual language, fewer resources, fewer experimental extras. If you're new to Linux and not comfortable with the command line yet, every source that compares these agrees on the same point: start with something more guided (ML4W's GUI-driven installer is the usual recommendation), not Caelestia or End-4.

It's also worth knowing the two projects aren't purely competitors, they actively borrow from each other. Contributors have ported features directly between the repos, a workspaces overview from End-4's dashboard was reimplemented in Caelestia's, and a calendar widget went the same direction into Caelestia's bar. If a feature you like exists in one but not the other, it's worth checking the other project's changelog before assuming it never will, cross-pollination between the two is common enough that it happens within the same release cycle.

Is Caelestia Shell Worth Installing?

Yes, if you're already running Hyprland, comfortable with the AUR or NixOS flakes, and want a single cohesive, wallpaper-themed interface instead of stitching Waybar, a launcher, a notification daemon and a lock screen together yourself. The wallpaper-driven color system is a real, working feature, not a marketing claim, and 12.6k GitHub stars reflect a genuinely active project rather than an abandoned rice.

The trade-offs are just as real: around 1.5 GB of idle RAM, heavier install (30-50 minutes and roughly 12 GB of disk on a fresh Arch system), and QML customization that's a harder skill floor than editing a Waybar JSON config. If you're new to Linux, still learning the command line, or running older hardware, you're better served by a lighter setup or a more guided installer like ML4W's. If neither of those is a dealbreaker, Caelestia is one of the best-supported Quickshell shells you can install today.

A quick way to decide, based on everything above: pick Caelestia if you want the End-4 look without the AI widgets and extra weight, and you're fine reading QML when you want a layout change rather than just a config value. Pick something lighter, Waybar plus separate tools, if resource use matters more to you than a unified animated interface, or if you're not ready to debug a shell built on a UI framework instead of flat config files. Pick your distro's bundled option (Omarchy's own shell, or Noctalia on CachyOS) if you'd rather have something maintained as part of the distro itself than a third-party project you update independently.

Troubleshooting Caelestia Shell: Common Problems and Questions

What is Caelestia Shell?

Caelestia Shell is a Quickshell-based desktop shell for Hyprland that replaces Waybar, your launcher, notification daemon and lock screen with a single animated interface that themes itself from your wallpaper.

Is Caelestia Shell the same as "Caelestia dots"?

No. caelestia-dots/shell is the shell component alone, installable on any existing Hyprland setup. caelestia-dots/caelestia ("Caelestia dots") is the full dotfiles bundle, Hyprland config, Fish shell and theming included, with its own automated installer.

Does Caelestia Shell work without Hyprland?

No. It's built specifically for Hyprland and won't run on GNOME, KDE Plasma, Sway or any other compositor or desktop environment.

How much RAM does Caelestia Shell use?

Independent testing puts idle usage around 1.5 GB, driven mainly by its animations. That's noticeably heavier than Waybar's near-zero footprint, worth checking against your hardware before installing.

Can I install Caelestia Shell on Omarchy?

Technically yes, since Omarchy runs Hyprland and, from version Quattro onward, its own system interface is also built on Quickshell. But that's the important caveat: Omarchy already ships its own Quickshell-based shell replacing Waybar, so installing Caelestia means replacing Omarchy's default shell, not adding something missing from it.

Do I need the AUR to install Caelestia Shell?

On Arch Linux, yes, the package comes from the AUR and needs a helper like yay or paru. On NixOS it's available through flakes instead. Outside those two, you're building manually from source.

Do I need to install caelestia-cli separately from caelestia-shell?

Yes. They are two separate AUR packages, not one combined package. caelestia-shell alone does not give you the CLI, which you need to properly start, restart and control the shell (wallpapers, color schemes, media players). Install both unless you have a specific reason not to.

Should I use caelestia-shell-git instead of the stable package?

Only if you specifically want unreleased features and are fine with occasional breakage during updates. For daily use, the stable caelestia-shell and caelestia-cli packages are the safer choice.

Where is Caelestia Shell's config file?

~/.config/caelestia/shell.json, which doesn't exist by default, you create it and only need to include the values you want to change from their defaults. Per-monitor overrides go in ~/.config/caelestia/monitors/<screen-name>/shell.json.

How do I update Caelestia Shell?

Through whatever installed it: your AUR helper (yay -Syu or paru -Syu) for caelestia-shell and caelestia-cli, or their -git equivalents, your normal flake update flow on NixOS, or a fresh git pull plus rebuild if you compiled it manually.

Can I customize Caelestia's layout, not just colors?

Yes, but it means editing QML modules, not shell.json. The recommended workflow is forking the repo and previewing changes live with qs -p shell.qml before copying them into your real install, editing files an AUR package installed directly gets overwritten on the next update.

"Couldn't resolve host" during installation

This is a DNS or network issue during dependency fetching, not a Caelestia bug. Check your network connection and DNS resolution (resolvectl status or /etc/resolv.conf) before retrying the install.

CLI commands don't work, or the shell won't start with "caelestia shell"

You installed caelestia-shell without caelestia-cli. Install caelestia-cli alongside it, or fall back to qs -c caelestia -n -d if you specifically don't want the CLI package.

No wallpaper showing, or the color scheme doesn't update

Almost always a config path or permissions issue after a fresh install. Confirm ~/.config/caelestia/ exists and is owned by your user, not root, a common side effect of running the manual CMake install without the final chown step, then set the wallpaper again through the launcher or CLI.

"hypr-vars.lua" error

This shows up specifically for people who installed before the project's migration to a Lua-based config format. If you're on an older install, follow the migration steps in the project's release notes rather than editing the Lua file directly, mismatched versions between the shell and your Hyprland config are the usual root cause.

Shell doesn't autostart with Hyprland

Check that your hyprland.conf actually has an exec-once line launching caelestia shell -d (or qs -c caelestia -n -d). If you used the automated installer, this should already be there, if you installed the shell manually on an existing Hyprland config, you need to add it yourself.

Is there a separate caelestia-dots/hypr repository for the Hyprland config alone?

No, there isn't a standalone repo just for the Hyprland-side config. The Hyprland configuration lives inside the main caelestia-dots/caelestia dotfiles repo and gets set up through its installer, not as a separate package.

Further Reading

• How to Install Omarchy on Arch Linux: Complete Setup Guide
• CachyOS: Install and Configure the Performance-Tuned Arch Linux Distro
• How to Install NixOS in 2026: The Flakes-First Way