# caelestia-kde: the Caelestia shell ported to KDE Plasma 6 on Wayland

> The Caelestia desktop shell was built for Hyprland. This port runs the same QML shell on KWin and Plasma 6, with a TUI installer, a Nexus settings app and a plugin store. Here is what it does, how to install it, and where it stops being the right choice.

**ladybug-me/caelestia-kde** — caelestia-shell ported to KDE plasma 6 

- Repository: https://github.com/ladybug-me/caelestia-kde
- Website: https://github.com/ladybug-me/wallpaper-collection
- Stars: 868 · Forks: 50
- Language: QML
- License: NOASSERTION
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/ladybug-me-caelestia-kde

## What caelestia-kde is, and who it is actually for

The Caelestia shell is a QML desktop shell originally written for Hyprland. caelestia-kde is the KDE Plasma port: according to the README, "Upstream runs on Hyprland; the port runs the same shell on KWin and Plasma." The repository describes itself as "caelestia-shell ported to KDE plasma 6", and the topics list confirms the stack: caelestia, dotfiles, kde, kde-theme, linux, qt6, quickshell, wayland.

That framing matters more than it first appears. This is not a Plasma theme, and it is not a widget pack. It replaces the shell layer itself: panels, dashboard, launcher, sidebar, overview, notification sidebar, clipboard history, screenshot and screen recording tools. The README lists keybinds for all of these, from Super + V for clipboard history to Super + Shift + D for text recognition. A Plasma theme changes how existing widgets are painted. This changes which widgets exist.

The audience is narrow and specific. You need KDE Plasma 6 on Wayland, on an Arch-based, Fedora or Debian/Ubuntu system. If you are on X11, the README's requirement line rules you out before installation starts. If you want a stock Plasma desktop with a different color scheme, this is a much larger commitment than you are looking for.

## How the port works: QML shell, C++ plugin, KWin instead of Hyprland

The repository layout tells most of the story. shell/ holds "the QML shell and its C++ QML plugin". src/ holds "files copied onto the system, plus the vendored submodules". scripts/ holds "install/update pipeline: the numbered steps and their shared lib/". The installer lives separately under installer/, with a C++ TUI source tree and per-distro package lists for arch, debian and fedora.

So the data flow on install is: the numbered step scripts in scripts/ copy files from src/ onto the system, build the C++ QML plugin, and install the shell. Design notes for this are kept under docs/architecture/, which is where I would look before changing anything structural.

The interesting part is the KWin substitution. On Hyprland, window management and the shell share a compositor that was designed to be scripted. On Plasma, KWin is the compositor and Plasma owns the panel and containment model. The port bridges that gap by running its own shell on top of KWin rather than inside Plasma's panel system. That is why the README warns that the stock KDE wallpaper manager does not drive the color scheme, and that using it "leaves the shell on stale colors". Two systems are both trying to own appearance, and only one of them is wired to the shell.

The colour path runs through kde-material-you-colors.service, a user systemd unit. The troubleshooting table points at it directly when colors fail to apply. Treat that service as part of the installation, not an optional extra.

## Installing caelestia-kde and getting to a first usable desktop

The README gives a single install command for the supported distributions. It pipes install.sh from the main branch into sh, so the script runs with your user's privileges and writes into your session.

```bash
curl -fsSL https://raw.githubusercontent.com/ladybug-me/caelestia-kde/main/install.sh | sh
```

Before running that, confirm two things: you are on KDE Plasma 6 on Wayland, and your base is Arch-based, Fedora or Debian/Ubuntu. The README states these as requirements, not preferences. If the install fails part-way through, the troubleshooting table says to re-run the setup step:

```bash
bash ./scripts/setup.sh
```

Once installed, open Nexus by pressing Super and then choosing >Settings. That is where appearance, panels, desktop rules, shortcuts and plugins are configured. Set the wallpaper from Appearance, not from KDE's own wallpaper manager, for the reason described above. Settings are written to ~/.config/caelestia/shell.json, so that file is the thing to back up before you experiment.

If widgets do not appear after install, the README's fix is to log out and back in, or to start the shell in debug mode:

```bash
caelestia shell -d
```

For detailed logs, enable Debug Mode in Nexus -> About -> Advanced and then run `caelestia shell -l`. That second command is the one worth remembering when a bug report is needed.

## Updating, and the branch choice you cannot avoid

Updates go through three routes, and all of them ask you to pick a branch. The installer TUI has an Update option. Nexus has Updates -> select branch -> Install Updates. The CLI route is:

```bash
bash update.sh
```

That command then asks you to choose `main` (stable) or `dev` (bleeding edge). The README states that shell settings are preserved across updates, which is the reassuring part. The less reassuring part is that the project ships a dev branch at all, and that the update flow exposes it as a first-class choice. If you pick dev, you are opting into whatever landed most recently.

Recent releases give a sense of cadence: v2.4.0 on 2026-09-06, v2.4.1 on 2026-09-09, v2.4.2 on 2026-09-12. Three releases in six days. That is a fast-moving tree, and the last push to the repository was on 2026-09-17. The repository is not archived, and the release cadence is current, but a fast cadence also means the stable branch is only as stable as the gap between releases allows. If you need a desktop that does not change under you, pin a release tag rather than tracking main.

Uninstalling is documented. Choose Uninstall from the installer TUI, or run:

```bash
bash ./uninstall.sh
```

The Makefile notes that uninstall removes "the shell, its configs and the lockscreen plugin". That third item is easy to forget: the lockscreen plugin is a separate installed component, and removing it is part of the same script.

## Where it breaks: X11, other distributions, and the wallpaper trap

The hardest constraint is Wayland. Plasma 6 runs on both Wayland and X11, and a large number of Plasma users are still on X11 for reasons that have nothing to do with fashion: remote desktop tools, certain GPU drivers, screen sharing setups. caelestia-kde is a Wayland shell. There is no documented X11 path, and the README does not discuss one. If your session is X11, stop here.

The distribution list is the second constraint. Arch-based, Fedora and Debian/Ubuntu are named. The installer/ directory has package lists under distro/ for arch, debian and fedora, which is consistent with that claim. A distribution outside those three has no package list and no documented install route. You could read scripts/ and adapt, but you would be maintaining a fork of the install pipeline.

The wallpaper behaviour is the third, and it is the one most likely to confuse a new user. KDE's own wallpaper manager is present and works, but the README is explicit that it does not drive the color scheme. Set a wallpaper through KDE and the shell keeps the previous palette. Nothing crashes; the desktop just looks wrong in a way that is hard to attribute. The fix is to set wallpapers from Appearance inside Nexus, and to remember that rule every time you change the background.

Finally, the installer is a curl pipe into sh. That is normal for dotfiles projects and it is also a real trust decision. The repository ships install.sh, update.sh and uninstall.sh at the root, plus the numbered steps under scripts/, so the whole pipeline is readable before you run it. Read it.

## Caelestia on Hyprland versus Caelestia on Plasma

The obvious alternative is the upstream project itself: caelestia-dots/shell, which the README credits as "the design language, shell and dotfiles this port is built on", alongside caelestia-dots/caelestia for the original Hyprland dotfiles. The difference is not cosmetic. Upstream targets Hyprland, where the compositor and the shell are designed together and configuration is a single coherent tree. The port targets KWin and Plasma, where the compositor is a separate project with its own configuration model, and where Plasma's own panel and containment system still exists underneath.

That means the two projects have different failure surfaces. Upstream problems tend to be Hyprland configuration problems. Port problems tend to be integration problems: color services not running, wallpaper managers fighting each other, Plasma components and shell components both claiming a surface. The troubleshooting table reflects this. Widgets not appearing, colors not applying, install failing mid-way: all three are integration symptoms, not shell-logic symptoms.

The other real alternative is to stay on stock Plasma 6 and get the Caelestia look through a theme and a widget set. You would keep Plasma's panel model, its settings application and its update path. You would not get the launcher, dashboard, sidebar, clipboard history or the plugin store. The trade is between a desktop that behaves like every other Plasma desktop and one that behaves like Caelestia. If you have not used Caelestia before, that trade is worth thinking about before you pipe a script into sh.

Licensing is GPL-3.0-or-later per the README and the LICENSE file. The GitHub metadata reports the licence as NOASSERTION, which is a metadata mismatch rather than a different licence. For a desktop shell you install on your own machine this changes little. If you intend to redistribute a modified build, the GPL-3.0-or-later terms in the LICENSE file govern, and the README's credits section lists upstream authors whose work is included.

## Reading the repository before you commit to it

The layout is unusually well organised for a dotfiles-adjacent project, and that organisation is the best signal available. installer/ splits the TUI, its data files and the per-distro package lists. scripts/ holds the numbered pipeline steps and a shared lib/, with bash tests for the step-script helpers under tests/. tools/ is explicitly "repo maintenance scripts, never shipped". docs/ has guides and design notes under docs/architecture/.

The Makefile reinforces the separation. Its header comment states that installing and updating stays with the root entry points "so the published `curl | sh` one-liner keeps working", and that everything in the Makefile is for working on the repo itself. The targets include `make test` for everything CI runs for tests, `make check` for everything CI runs for lint, and `make build-shell`, which builds and installs the C++ QML plugin and needs Qt6 plus CMake on Linux. That last target is the one to know if you are modifying the shell rather than just using it.

There is also a crowdin.yml at the root, which points at translation tooling, and the Makefile has `translations` and `sync-fetch` targets. The README does not document a translation workflow, so that is a gap if you were hoping to contribute strings.

What the README does not document: rollback. There is an update path with a branch selector and a documented uninstall, but no stated procedure for reverting to a previous release after an update goes wrong. If that matters to you, snapshot ~/.config/caelestia/shell.json and note the release tag you installed before running update.sh.

## Conclusion

Adopt caelestia-kde if you already run KDE Plasma 6 on Wayland and want the Caelestia look without switching to Hyprland; skip it if you are on X11, on a non-Arch/Fedora/Debian base, or unwilling to let an installer write into your session. Before installing, read install.sh and scripts/setup.sh, confirm kde-material-you-colors.service is present, and decide whether you want the main or dev branch, because the update path asks you to choose.

## FAQ

### How do I remove caelestia-kde?

Choose Uninstall from the installer TUI, or run `bash ./uninstall.sh` from the repository. The Makefile describes that target as removing the shell, its configs and the lockscreen plugin.

### What is the caelestia shell?

It is a QML desktop shell that replaces the panel, launcher, dashboard, sidebar, overview and notification surfaces. caelestia-kde is the KDE Plasma port of caelestia-dots/shell, which upstream runs on Hyprland.

### What is KDE Plasma used for in this setup?

Plasma 6 provides the desktop session and KWin provides the compositor, while caelestia-kde runs its own shell on top. The README requires KDE Plasma 6 on Wayland, and the stock KDE wallpaper manager does not drive the shell's color scheme.

## Sources

- [Issues](https://github.com/ladybug-me/caelestia-kde/issues)
- [ladybug-me/caelestia-kde on GitHub](https://github.com/ladybug-me/caelestia-kde)
- [Project website](https://github.com/ladybug-me/wallpaper-collection)
- [README](https://github.com/ladybug-me/caelestia-kde/blob/main/README.md)
- [Releases](https://github.com/ladybug-me/caelestia-kde/releases)

---

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