# caelestia-dots/shell: a Quickshell-based desktop shell for Hyprland

> Caelestia's shell is a QML desktop layer built on Quickshell and aimed at Hyprland users on Wayland. It ships through the AUR, Nix, or a CMake build, and it expects a long dependency list before it will start.

**caelestia-dots/shell** — A fluid, morphing shell for your Linux desktop

- Repository: https://github.com/caelestia-dots/shell
- Website: https://caelestiashell.com
- Stars: 12,617 · Forks: 919
- Language: QML
- License: GPL-3.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/caelestia-dots-shell

## What caelestia-shell actually replaces on a Hyprland desktop

Hyprland gives you a compositor and a config language. It does not give you a bar, a launcher, a notification surface, or a lock screen. Those come from separate programs, and most Hyprland setups end up stitching together waybar, rofi or fuzzel, mako or dunst, swaylock, and a handful of scripts. Each piece has its own config format, its own theme system, and its own idea of how a popup should animate.

caelestia-shell is one program that covers that layer. The README lists its components as Quickshell for widgets, Hyprland as the window manager, and the caelestia dotfiles repository as the surrounding configuration. So the shell is not a standalone desktop environment. It is the visual and interactive surface that sits on top of a Hyprland session, and the dotfiles repository is where the Hyprland side of the setup lives.

The audience is narrow and clearly stated. This repository is described as the shell only, with a note pointing anyone who wants the whole dotfiles setup, which includes the shell, at the main repository instead. If you are looking for a complete desktop configuration, this is the wrong entry point.

## Quickshell, QML and the IPC surface

The shell is written in QML, which is why the repository is dominated by QML files and directories such as components, modules, services, utils, and the top-level shell.qml. Quickshell is the runtime that hosts those QML files and exposes them as a Wayland layer shell surface.

Interaction with the running shell goes through two paths. The first is Hyprland global shortcuts, which the README links to in the Hyprland wiki under dbus global shortcuts. The second is IPC, reached through the caelestia CLI. The README gives a concrete example: running caelestia shell mpris getActive trackTitle returns the title of the currently active media player track. The full command list is available by running caelestia shell -s.

That CLI is not optional in practice. The README states that the default Nix package does not include the CLI, and that full functionality comes from the with-cli package variant. Manual installs list caelestia-cli as a dependency. So the shell binary and the control surface are packaged separately, and picking the wrong package leaves you with a shell you cannot query or drive from the command line.

The repository also carries a plugin directory and a CMakeLists.txt at the top level, which matches the README's description of a build step that produces a QML plugin and a version helper library alongside the config files.

## Installing caelestia-shell on Arch with an AUR helper

The README's recommended path for Arch Linux is the AUR package caelestia-shell, installed through an AUR helper such as paru, or by downloading the PKGBUILD and running makepkg -si. A second package, caelestia-shell-git, tracks the latest commit. The README calls that one bleeding-edge and likely to be unstable or buggy, and recommends the stable package for regular users.

The README carries a warning here that is easy to skip: if you intend to make your own changes or tweaks, do not edit the files installed by the AUR package. The manual installation section is the supported route for that. Editing package-managed files means the next upgrade overwrites your work.

Once installed, the documented way to start the shell is the caelestia CLI:

```bash
caelestia shell -d
```

The -d flag detaches the shell from the terminal. The README notes that omitting it keeps the shell attached to the current terminal, which is useful for debugging but means the shell exits when you close that terminal. An alternative invocation, qs -c caelestia -n -d, is also given. If you are using the Caelestia dotfiles, the shell is autostarted at login through a hl.on("hyprland.start", ...) call in the Hyprland config, and the keybinds are already wired up.

## Running it under Nix, and the package variant that matters

For Nix users the README offers a direct run command:

```sh
nix run github:caelestia-dots/shell#with-cli
```

The with-cli suffix is the point. The README states that the default package does not include the CLI, so a plain nix run without that suffix gives you the shell without the caelestia command that the README uses for IPC and for starting the shell.

For a system configuration, the flake is added as an input, with the README's example following nixpkgs so the two do not pull separate copies:

```nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    caelestia-shell = {
      url = "github:caelestia-dots/shell";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}
```

The README says the with-cli package can go into environment.systemPackages, users.users.<username>.packages, home.packages under home-manager, or a devshell. It also mentions a Caelestia Home Manager module that installs and configures both the shell and the CLI, with details in a configuration section that is not part of the text available here. If you use home-manager, that module is the least manual route, but you will need to read the configuration section on the project's own documentation to know what it sets.

## The manual build and its dependency surface

Manual installation is where the real cost of this project shows. The README lists roughly two dozen runtime dependencies, including caelestia-cli, ddcutil, brightnessctl, libcava, networkmanager, lm_sensors, aubio, libpipewire, libqalculate, power-profiles-daemon, swappy, fish, bash, several Qt6 modules, and three font packages. Build dependencies are cmake, ninja, and qt6-shadertools.

One entry stands out: quickshell-git. The README states this has to be the git version, not the latest tagged version. That single line rules out a lot of distributions, because a packaged quickshell from a stable repository will not satisfy it. If your distribution ships Quickshell as a tagged release and you do not want to build from git, this project is not for you.

The clone and build sequence is given as follows, assuming $XDG_CONFIG_HOME is set:

```sh
cd $XDG_CONFIG_HOME/quickshell
git clone https://github.com/caelestia-dots/shell.git caelestia

cd caelestia
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/
cmake --build build
sudo cmake --install build
```

The README notes that if $XDG_CONFIG_HOME is unset you should substitute the path to your config folder, typically ~/.config. It also documents three CMake flags for relocating parts of the install: INSTALL_LIBDIR for libraries such as the version helper, INSTALL_QMLDIR for the QML plugin, and INSTALL_QSCONFDIR for the Quickshell config. If you set INSTALL_LIBDIR, the README says CAELESTIA_LIB_DIR must be set to the same directory in your environment. That is a two-place change, and forgetting the second half is a plausible source of a shell that builds cleanly and then fails to find its own library.

## Where caelestia-shell stops being the right choice

The dependency list is the clearest boundary. This is a Wayland and Hyprland project. The topics list hyprland and wayland, the components section names Hyprland as the window manager, and the keybind integration is described through Hyprland global shortcuts. Nothing in the README describes support for another compositor or for X11. If you run Sway, KDE, GNOME, or an X11 session, the documented integration points do not apply to you.

Distribution support is the second boundary. The README documents Arch Linux through the AUR, Nix, and a manual CMake build. There is no documented package for Fedora, Debian, openSUSE, or anything else. The manual route is technically distribution-agnostic, but it assumes you can obtain quickshell-git, qt6-m3shapes-git, and the font packages yourself. On a distribution that does not package those, you are building a stack, not installing a shell.

The third boundary is stability expectations. The README itself labels the caelestia-shell-git package as bleeding-edge and likely to be unstable or buggy. That is the project's own description of its rolling package, and it is worth taking at face value if you need a desktop that behaves the same way every morning.

Finally, the README is incomplete as a standalone document. The profile picture and wallpaper section is cut off mid-sentence in the available text, the Home Manager module points at a configuration section not reproduced here, and the Updating section is referenced by the installation notes but its contents are not shown. Anyone planning a manual install should read the full README and the linked configuration documentation rather than relying on the installation excerpt alone.

## How it differs from assembling separate Wayland tools

The obvious alternative is the conventional Hyprland stack: waybar for the bar, a launcher such as rofi or fuzzel, a notification daemon, and a lock screen, each configured independently. The difference is architectural rather than cosmetic. Those tools are separate processes with separate config formats, and they coordinate only through whatever the compositor and the system bus expose. caelestia-shell is a single Quickshell process hosting QML components, which is why it can present a coherent animation and theming story and why the README can describe it as morphing.

The trade-off runs the other way too. With separate tools you can replace one piece without touching the rest, and a crash in the bar does not take the launcher with it. With caelestia-shell, the whole surface is one process and one codebase. The README's own instruction not to edit AUR-installed files, and to use the manual install for local changes, reflects that: customisation happens at the source level, not through a small config file.

Quickshell itself is the other comparison point. Caelestia's shell is one consumer of it. If you want to write your own QML shell rather than adopt someone else's, Quickshell is the layer you would build on, and this repository is a worked example of doing that at scale, with services, modules, components and a plugin directory. Reading its layout is a reasonable way to learn the runtime even if you never run the shell.

## Conclusion

Adopt it if you already run Hyprland on Wayland, want a widget layer written in QML, and are willing to satisfy the full dependency list, including the git build of quickshell rather than a tagged release. Skip it if you are on X11 or a non-Arch, non-Nix distribution, because the README documents only AUR, Nix and manual CMake paths, and the manual route assumes you can supply every package yourself. Before installing, read the AUR warning about not editing package-installed files, and check the Updating section of the README, which is referenced but not reproduced in the installation text.

## FAQ

### What is caelestia-shell used for?

It provides the desktop shell layer for a Hyprland session on Wayland: widgets, bar and popups, built with Quickshell and QML. It is the shell only, not the full dotfiles setup, and the README points at the main caelestia repository for the complete configuration.

### How do I install caelestia-shell?

On Arch Linux the README recommends the AUR package caelestia-shell, installed with an AUR helper such as paru or by running makepkg -si on the PKGBUILD. Nix users can run nix run github:caelestia-dots/shell#with-cli or add the flake as an input, and there is also a manual CMake build path.

### Why does the manual installation require quickshell-git instead of a released Quickshell?

The README lists quickshell-git as a dependency and states explicitly that it has to be the git version, not the latest tagged version. That means a distribution-packaged Quickshell built from a release will not satisfy the documented requirement.

### Does caelestia-shell work outside Hyprland?

Nothing in the README describes support for another compositor or for X11. The components section names Hyprland as the window manager, and keybind integration is documented through Hyprland global shortcuts.

## Sources

- [caelestia-dots/shell on GitHub](https://github.com/caelestia-dots/shell)
- [License: GPL-3.0](https://github.com/caelestia-dots/shell/blob/main/LICENSE)
- [Project website](https://caelestiashell.com)
- [README](https://github.com/caelestia-dots/shell/blob/main/README.md)
- [Releases](https://github.com/caelestia-dots/shell/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/caelestia-dots-shell