A complete guide to installing Caelestia Shell on Ubuntu 25.10. Caelestia is a beautiful, feature-rich desktop shell built with Quickshell for Hyprland.
Note: Caelestia was designed for Arch Linux (AUR packages). This guide covers building everything from source on Ubuntu.
- One script for a clean, repeatable setup
- Source builds for Quickshell, Caelestia CLI, libcava, and Caelestia Shell
- Working configs you can copy as-is or tweak
- Clear manual steps when you want full control
Prerequisites: Ubuntu 25.10 with Hyprland already installed (see Step 1 below).
git clone https://github.com/IshmamDC217/caelestia-shell-ubuntu.git
cd caelestia-shell-ubuntu
./install.shThe script will:
- Install all APT dependencies in one go
- Download and install CascadiaCode Nerd Font
- Build and install Quickshell, libcava, Caelestia CLI, and Caelestia Shell
- Set up library paths and environment variables
- Copy included config files to the right locations
Build sources are kept in ~/caelestia-build/ and can be removed after installation.
| File | Destination | Description |
|---|---|---|
config/shell.json |
~/.config/caelestia/shell.json |
Caelestia shell configuration |
config/quickshell/qml_color.json |
~/.config/quickshell/qml_color.json |
Quickshell color theme |
config/hypr/hyprland.conf |
~/.config/hypr/hyprland.conf |
Hyprland config (reference only) |
config/bashrc.snippet |
append to ~/.bashrc |
QML_IMPORT_PATH environment variable |
install.sh |
-- | Automated installer script |
The QML import path must be set for Caelestia to find its modules:
In ~/.bashrc (for terminal/CLI usage):
export QML_IMPORT_PATH=/usr/lib/qt6/qmlIn ~/.config/hypr/hyprland.conf (for Hyprland session):
env = QML_IMPORT_PATH,/usr/lib/qt6/qmlThe install script handles the bashrc entry automatically. The hyprland.conf line must be added manually if not already present.
- Ubuntu 25.10 (may work on 24.04 with adjustments)
- A working Wayland session
- ~2GB free disk space for building
Use JaKooLit's Ubuntu-Hyprland installer:
git clone -b 25.10 --depth=1 https://github.com/JaKooLit/Ubuntu-Hyprland.git ~/Ubuntu-Hyprland-25.10
cd ~/Ubuntu-Hyprland-25.10
chmod +x install.sh
./install.shRecommended options:
| Prompt | Recommended |
|---|---|
| Monitor resolution | Option 2 (>= 1440p) |
| GTK Themes | Yes |
| Thunar | Yes |
| SDDM | No (keep GDM) |
| XDG-Desktop-Portal-Hyprland | Yes |
| Preconfigured Dotfiles | Yes |
| Add to input group | Yes |
Reboot and select "Hyprland" from GDM.
sudo apt update
sudo apt install -y build-essential cmake ninja-build git pkg-config mesonsudo apt install -y \
qt6-base-dev \
qt6-declarative-dev \
qt6-svg-dev \
qt6-wayland-dev \
qt6-wayland \
qt6-shader-baker \
libqt6svg6 \
libwayland-dev \
wayland-protocols \
libjemalloc-dev \
libpipewire-0.3-dev \
libxcb1-dev \
libdrm-devsudo apt install -y \
python3-pip \
python3-build \
python3-hatchling \
libnotify-bin \
grim \
slurp \
wl-clipboard \
fish \
brightnessctl \
ddcutil \
lm-sensors \
swappy \
libqalculate-dev \
libaubio-devmkdir -p ~/.local/share/fonts
cd /tmp
wget https://github.com/ryanoasis/nerd-fonts/releases/download/v3.3.0/CascadiaCode.zip
unzip CascadiaCode.zip -d CascadiaCode
cp CascadiaCode/*.ttf ~/.local/share/fonts/
fc-cache -fvcd ~
git clone https://git.outfoxxed.me/quickshell/quickshell.git
cd quickshell
cmake -GNinja -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo \
-DCMAKE_INSTALL_PREFIX=/usr \
-DCRASH_REPORTER=OFF \
-DINSTALL_QML_PREFIX=lib/qt6/qml
cmake --build build
sudo cmake --install buildImportant: Use LukashonakV/cava fork, NOT karlstav/cava.
cd ~
git clone https://github.com/LukashonakV/cava.git libcava
cd libcava
meson setup build --buildtype=release -Ddefault_library=shared
meson compile -C build
sudo meson install -C buildConfigure library path:
echo "/usr/local/lib/x86_64-linux-gnu" | sudo tee /etc/ld.so.conf.d/libcava.conf
sudo ldconfigcd ~
git clone https://github.com/caelestia-dots/cli.git caelestia-cli
cd caelestia-cli
python3 -m build --wheel
sudo pip3 install dist/*.whl --break-system-packagesmkdir -p ~/.config/quickshell
cd ~/.config/quickshell
git clone https://github.com/caelestia-dots/shell.git caelestia
cd caelestia
PKG_CONFIG_PATH="/usr/local/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH" \
cmake -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/
cmake --build build
sudo cmake --install buildVerify:
ls -la /usr/lib/qt6/qml/Caelestia/Services/Add to ~/.bashrc:
export QML_IMPORT_PATH=/usr/lib/qt6/qmlAdd to ~/.config/hypr/hyprland.conf:
env = QML_IMPORT_PATH,/usr/lib/qt6/qmlmkdir -p ~/Pictures/Wallpapers
# Add wallpapers to this directoryCopy config/shell.json from this repo to ~/.config/caelestia/shell.json, or create your own.
Key settings:
services.useFahrenheit:falsefor Celsiusservices.gpuType:"intel","amd", or"nvidia"background.visualiser.enabled:falseto disable audio visualizer
Copy config/quickshell/qml_color.json from this repo to ~/.config/quickshell/qml_color.json. This controls the Quickshell color scheme. Caelestia will regenerate this file when you change themes.
caelestia shell -dAdd to ~/.config/hypr/hyprland.conf:
exec-once = caelestia shell -dRebuild both Quickshell and caelestia-shell with PKG_CONFIG_PATH set:
export PKG_CONFIG_PATH="/usr/local/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH"Use -DCMAKE_INSTALL_PREFIX=/ (not /usr).
export QML_IMPORT_PATH=/usr/lib/qt6/qml- Caelestia Dots - Original shell by Scout
- Hyprland by @vaxry - Wayland compositor
- Quickshell by @outfoxxed - Shell framework
- JaKooLit - Ubuntu Hyprland installer
- LukashonakV - libcava fork
GPL-3.0