Home arch linux caelestia dotfiles hyprland musabase guides How to Manually Install Caelestia Dotfiles on Hyprland: Complete Arch Linux Guide

How to Manually Install Caelestia Dotfiles on Hyprland: Complete Arch Linux Guide

How to Manually Install Caelestia Dotfiles on Hyprland: Complete Arch Linux Guide

How to manually install Caelestia dotfiles on Hyrpland

Amid cluttered interfaces and flashy distractions, it’s uncommon to come across a setup that puts focus first without compromising on visual appeal. The Caelestia dotfiles bring a quiet precision to Arch Linux that few desktop environments can truly match.

This guide is part of the MusaBase Linux and Hyprland Series. For a complete overview, see the Best Hyprland Dotfiles Best Hyprland Dotfiles for Linux: Compared and Tested and the Arch Linux Roadmap.

Welcome back to MusaBase! in todays guide, we will be manually installing Caelestia dotfiles on Hyprland. In the previous guide we installed Caelestia Dotfiles with autoinstaller that handled all the packages, symlinking and configuration automaticlly but today we are going to do everything manually from installation of core packages, to handling compiling, to applying Caelesita dotfiles on Hyprland.

This is exactly, what we are going to cover in this guide:

  1. Manually Install Core Dotfile Dependencies.
  2. Install Caelesita CLI.
  3. Install Caelestia Shell Dependencies.
  4. Build and install Caelestia Shell.
  5. Logging into Hyprland with Caelestia Dotfiles.
  6. And also, fixing missing wallpaper error for Caelestia dotfiles.

By the end of this guide, you would have fully functional Caelestia dotfiles Hyprland running on your system that you manually install and configured.

Neofetch Caelestia dotfiles Hyprland on Arch Linux




Prerequisites: What You Need Before Installing Caelestia Dotfiles

Before you begin the manual installation of Caelestia dotfiles on Hyprland, make sure you have the following essentials in place:

  1. A base Arch Linux system: This guide does not cover Arch Linux installation itself. If you haven't installed Arch yet, follow my Arch Linux UEFI installation or Arch Linux with Btrfs Filesystem Snapshot Ready guide. Installing without a desktop environment is highly recommended for a clean setup.
  2. The yay AUR helper: Since most packages for Caelestia dotfiles come from the AUR, yay is essential. I've covered yay installation in my complete daily-driver guide.

Note: You don't need to follow the entire daily-driver article, just complete the "Install AUR helper yay" step, then return here to proceed with the Caelestia dotfiles manual installation.



⚡ TL;DR: Manually Install Caelestia Dotfiles on Hyprland

A quick reference for the essential commands to manually install Caelestia dotfiles on Arch Linux with Hyprland – from core dependencies to building the shell and symlinking configurations.

  1. Install core dependencies: 
    yay -S hyprland kitty xdg-desktop-portal-hyprland xdg-desktop-portal-gtk \
hyprpicker wl-clipboard cliphist inotify-tools app2unit wireplumber \
trash-cli foot fish fastfetch starship uwsm btop jq eza adw-gtk-theme \
papirus-icon-theme qtengine-git ttf-jetbrains-mono-nerd
  2. Install Caelestia CLI dependencies and build the wheel: 
    yay -S libnotify swappy grim dart-sass slurp gpu-screen-recorder glib2 fuzzel \
python-build python-installer python-hatch python-hatch-vcs

git clone https://github.com/caelestia-dots/cli.git
cd cli
python -m build --wheel
sudo python -m installer dist/*.whl
sudo cp completions/caelestia.fish /usr/share/fish/vendor_completions.d/caelestia.fish
cd ..
  3. Install shell dependencies and build tools: 
    yay -S quickshell-git ddcutil brightnessctl libcava networkmanager lm_sensors \
aubio libpipewire qt6-declarative qt6-base gcc-libs glibc bash libqalculate \
ttf-material-symbols-variable-git ttf-cascadia-code-nerd

sudo pacman -S cmake ninja
  4. Build and install Caelestia Shell: 
    sudo mkdir -p ~/.config/quickshell
sudo chown -R $USER:$USER ~/.config/quickshell
cd ~/.config/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
  5. Clone main repo and symlink configs: 
    git clone https://github.com/caelestia-dots/caelestia.git ~/.local/share/caelestia
cd ~/.local/share/caelestia

ln -sf ~/.local/share/caelestia/hypr ~/.config/hypr
ln -sf ~/.local/share/caelestia/foot ~/.config/foot
ln -sf ~/.local/share/caelestia/fish ~/.config/fish
ln -sf ~/.local/share/caelestia/fastfetch ~/.config/fastfetch
ln -sf ~/.local/share/caelestia/uwsm ~/.config/uwsm
ln -sf ~/.local/share/caelestia/btop ~/.config/btop
cp ~/.local/share/caelestia/starship.toml ~/.config/starship.toml
  6. Install SDDM login manager: 
    sudo pacman -S sddm
sudo systemctl start sddm
  7. Troubleshooting: fix hypr-vars.lua error (if needed): 
    mkdir -p ~/.config/caelestia
cat > ~/.config/caelestia/hypr-vars.lua << 'EOF'
return {}
EOF

cat > ~/.local/share/caelestia/hypr/hypr-vars.lua << 'EOF'
return {}
EOF
  8. Fix Caelestia Shell not autostarting (if needed): 
    sudo nano ~/.config/hypr/hyprland.conf
    Add this line to the config file: 
    exec-once = qs -c caelestia
  9. Fix dynamic color scheme (if colors aren't changing): 
    sudo pacman -S python-pip
pip install materialyoucolor --break-system-packages
caelestia scheme set -n dynamic

πŸ’‘ After logging in via SDDM, you should see the Caelestia Hyprland session. If you encounter any issues, refer to the troubleshooting section above for detailed fixes. Your manually installed Caelestia dotfiles are now ready to use!



Step 1: Install Core Dependencies for Caelestia Dotfiles

In this step, we are going to install the essential packages needed for a base UI. For Caelestia dotfiles, we only need a few basic UI packages like Hyprland, xdg-desktop-portal, xdg-desktop-portal-gtk, and others.

Run the following command:

yay -S hyprland kitty xdg-desktop-portal-hyprland xdg-desktop-portal-gtk \
hyprpicker wl-clipboard cliphist inotify-tools app2unit wireplumber \
trash-cli foot fish fastfetch starship uwsm btop jq eza adw-gtk-theme \
papirus-icon-theme qtengine-git ttf-jetbrains-mono-nerd
  1. By running this command, yay will prompt for Packages to cleanbuild? and Diffs to show? Just press ENTER to continue.
  2. After downloading the core dependencies with their helper packages, yay will prompt for Remove make dependency after install (y,N)?. Here again, press ENTER to not remove make dependencies after install. However, if you don't need those dependencies, just type y and press ENTER to remove them after building.
  3. Some packages will be built from source; in total, it will take around 2-5 minutes.
Manually installing Caelestia dotfiles core dependencies on Arch Linux
Manual installation of Caelestia dotfiles core dependencies completed successfully

With core packages for Caelestia dotfiles installed, let's head to installing Caelestia CLI in the next step.



Step 2: Install Caelestia CLI

In this step, we will manually install Caelestia CLI by cloning its GitHub repository and building it with Python, in addition to installing the packages required for Caelestia CLI.

2.1: Install Caelestia CLI Packages

Run the following command:

yay -S libnotify swappy grim dart-sass slurp gpu-screen-recorder glib2 fuzzel python-build python-installer python-hatch python-hatch-vcs
Manually installing Caelestia CLI packages
Manual installation of Caelestia CLI packages completed

2.2: Clone Caelestia CLI Repo, Build and Install

  1. First, we will clone the Caelestia CLI repository from GitHub and cd into the repo.
  2. Then, we will build the wheel with Python.
  3. Finally, we will install it.
  4. Run the following commands consecutively:
git clone https://github.com/caelestia-dots/cli.git
cd cli
python -m build --wheel
sudo python -m installer dist/*.whl
Cloning Caelestia CLI GitHub repository
Building the wheel for Caelestia CLI manually Installing the Caelestia CLI build

2.3: Install Fish Completions

To install the fish completions that is just the files that we build manually above, we need to copy it from the Caelestia CLI folder and paste it into /usr/share/fish/vendor_completions.d/caelestia.fish. Run the following command:

sudo cp completions/caelestia.fish /usr/share/fish/vendor_completions.d/caelestia.fish
cd ..
Installing caelestia.fish completions

Now that Caelestia CLI is successfully installed, we're ready to move on to the next phase: installing the Caelestia shell dependencies.



Step 3: Install Caelestia CLI and Build Dependencies

First, we will install the Caelestia shell dependencies, which also include building and compiling packages from source.

3.1: Install Caelestia CLI Dependencies

Run the following command to install Caelestia CLI dependencies:

yay -S quickshell-git ddcutil brightnessctl libcava networkmanager lm_sensors aubio libpipewire qt6-declarative qt6-base \
gcc-libs glibc bash libqalculate ttf-material-symbols-variable-git ttf-cascadia-code-nerd
  1. As usual, yay will prompt for packages to cleanbuild, diffs to show, and remove make dependency after install. Press ENTER to continue.
  2. For these packages, yay will build and compile some packages from source.
  3. On my device, it took roughly 8 minutes to complete this process.
Manually installing Caelestia shell dependencies
Yay building Caelestia shell dependencies from source Manual installation of Caelestia shell dependencies completed

3.2: Install Build Dependencies

Run the following command:

sudo pacman -S cmake ninja

With build dependencies installed, let's build and install Caelestia Shell in the next step.



Step 4: Manually Build and Install Caelestia Shell

With all the required dependencies and tools installed, in this step, we will clone and build the Caelestia shell manually.

  1. Now, we need to create the quickshell folder at ~/.config/quickshell.
  2. Then, change the current directory to ~/.config/quickshell.
  3. Run the following commands consecutively:
sudo mkdir -p ~/.config/quickshell
sudo chown -R $USER:$USER ~/.config/quickshell
cd ~/.config/quickshell
Making directory for Caelestia quickshell manually and changing its permissions
  1. Now we will clone the Caelestia shell repository from GitHub and cd into it.
  2. Then prepare the build files with Ninja.
  3. Run the following commands consecutively:
git clone https://github.com/caelestia-dots/shell.git caelestia
cd caelestia
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/
Cloning Caelestia Shell repository from GitHub
Changing directory to cloned Caelestia shell repository and preparing build files with Ninja Build files generated successfully

Next, build the Caelestia shell with:

cmake --build build
Manually building Caelestia Shell
Caelestia shell built successfully manually

Next, we can finally install the Caelestia shell build by running:

sudo cmake --install build
Installing Caelestia build manually
Caelestia shell build manually installed successfully

Now that the manual build and installation of Caelestia Shell is done, let's move to cloning the Caelestia main repo and symlinking configs in the next step.





Step 6: Install Login Manager

To log in to the Caelestia dotfiles Hyprland session, we can install a login manager such as SDDM. We can also jump into the Hyprland session by running uwsm start hyprland, but currently, running Hyprland manually is causing some issues on my system. So, I will stick with the login manager.

Install SDDM

Run the following command:

sudo pacman -S sddm

To start sddm, run:

sudo systemctl start sddm
SDDM with Hyprland session ready to login into Caelestia Dotfiles

Now we can log in to our Hyprland session with Caelestia dotfiles and experience its unique approach to theming and styling. However, if there are some issues when starting the Hyprland session with Caelestia dotfiles, such as hypr-vars.lua not being found, require('hypr-vars') failing, or the Caelestia shell not starting at all, we will fix these issues in the Fixing Caelestia Dotfiles Not Starting section.



Caelestia Dotfiles

After logging in or if you manually started Hyprland with uwsm start hyprland, you will see the following screen:

Experience Caelestia dotfiles manually installed on Arch Linux

A Little Showcase: Caelestia Dotfiles

Neofetch manually installed Caelestia dotfiles on Arch Linux
Showcasing Caelestia dotfiles changing color scheme with wallpaper Showcasing Caelestia dotfiles materilyoucolor capabilities Caelestia dotfiles


Troubleshoot: Caelestia Dotfiles Not Starting

In this Caelestia dotfiles troubleshooting section, we are going to fix common errors we face, such as "couldn't resolve host" while installing packages during installation, or when we start the Hyprland session, where either the Caelestia dotfiles don't start at all or Hyprland has .lua issues. The most common errors I faced were:

Couldn't resolve host during Installation

If during installation you get the following error:

Download error while retrieving file

This does not mean the package is missing or that there is a problem with the AUR. In most cases, it is caused by one of the following:

  • Network or Firewall Restrictions: Your local firewall, ISP, or proxy may be blocking outbound connections on certain ports.
  • Mirror Issues: The selected package mirror may be slow, temporarily down, or undergoing maintenance.
  • DNS Problems: Your configured nameserver may be failing to resolve the mirror's IP address.

We can quickly fix this by running the following commands:

sudo echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
sudo pacman -Syyu

This should be treated as a quick and temporary fix. For a complete solution, I've documented a full dedicated article in my Fixing Slow Pacman Downloads on Arch Linux guide. If you face the same issue, you can also try installing the packages while connected to a VPN.


hypr-vars.lua Error

If you start your Hyprland session and get this screen instead of Caelestia's shell:

Caelestia dotfiles hypr-vars.lua error
  • Exit the Hyprland session by pressing either SUPER + M, META + M, or WINDOW-KEY + M, or by just rebooting the system.
  • Next, in the tty1 session screen or CLI screen, fix the error explained below according to your issue.

To fix hypr-vars.lua errors, we need to:

  1. Create the ~/.config/caelestia directory.
  2. Create the hypr-vars.lua file at ~/.config/caelestia.
  3. Create the hypr-vars.lua file where it is actually required, at ~/.local/share/caelestia/hypr/.
  4. Run the following steps consecutively:
mkdir -p ~/.config/caelestia
cat > ~/.config/caelestia/hypr-vars.lua << 'EOF'
return {}
EOF

cat > ~/.local/share/caelestia/hypr/hypr-vars.lua << 'EOF'
return {}
EOF
Fixing Caelestia dotfiles hypr-vars.lua error

Caelestia Dotfiles Not Autostarting with Hyprland

This issue is completely different from the Fixing hypr-vars.lua issue. Follow this step if your Hyprland session starts normally without any major errors, but the Caelestia shell doesn't start with it. For this issue, we only need to:

  1. Open the ~/.config/hypr/hyprland.conf file.
  2. Add the qs -c caelestia execution and reboot the system.
  3. Run the following command:
    4. sudo nano ~/.config/hypr/hyprland.conf
  4. In the hyprland.conf file, add:
    5. exec-once = qs -c caelestia
  5. After adding the exec line, press CTRL + O to save the changes, then press ENTER to confirm, and finally press CTRL + X to exit the file.
  6. Reboot, and when you boot into Hyprland again, Caelestia Shell will start automatically with it.
Opening hyprland.conf file to add Caelestia shell exec
Adding the qs -c caelestia line to hyprland.conf to autostart Caelestia Shell with Hyprland session

Fixing the "No Wallpaper" Issue in Caelestia Dotfiles

If you're facing a missing or blank wallpaper issue, I've already covered this in my Caelestia Dotfiles auto-installation guide. To resolve it, simply visit that guide and follow the Fix Missing Wallpapers section, this solution works perfectly for manual installations as well.


Color Scheme Not Working

If you are getting this error again and again while running Caelestia dotfiles:

from caelestia.utils.wallpaper import get_colours_for_wall, get_wallpaper, set_random, set_wallpaper
File "/usr/lib/python3.14/site-packages/caelestia/utils/wallpaper.py", line 10, in <module>
from materialyoucolor.hct import Hct
ModuleNotFoundError: No module named 'materialyoucolor'

Or if the colors are not vibrant or properly showing like this:

Caelestia dotfiles colors are not properly displaying

It's because materialyoucolor wasn't implemented properly. One of the most intriguing features that kept me on Caelestia dotfiles for 6 months before my shift to Omarchy, was Caelestia's materialyoucolor. It changes the whole color scheme according to my current wallpaper. And in the manual Caelestia dotfiles installation, we also have to manually set it by doing the following:

sudo pacman -S python-pip
pip install materialyoucolor --break-system-packages
caelestia scheme set -n dynamic
Installing materialyoucolor with pip for dynamic color scheme on Caelestia dotfiles
Caelestia dynamic color scheme fix

This will fix the color scheme error.



Frequently Asked Questions

What are the prerequisites for manually installing Caelestia dotfiles?

You need a base Arch Linux system (installed without a desktop environment) and the yay AUR helper. I've covered both in my Arch Linux UEFI installation and yay installation guides.

How is manual installation different from the auto-installer?

With the auto-installer, everything is handled automatically, packages, symlinking, and configurations are all taken care of. In this manual guide, you install each component step by step: core dependencies, Caelestia CLI, shell dependencies, and then build and install the Caelestia Shell yourself. This gives you full control over the process and a deeper understanding of how everything fits together.

How long does the manual installation take?

On my test machine, the entire process took roughly 15–20 minutes depending on your internet speed and system performance. The core dependencies take 2–5 minutes, the shell dependencies take about 8 minutes, and the remaining steps (CLI, build, symlinking) add a few more minutes.

Do I need to install a desktop environment first?

No, in fact, it's highly recommended to install Arch Linux without a desktop environment. Caelestia dotfiles use Hyprland as the Wayland compositor, and everything is built from the ground up for a clean, minimal setup.

What should I do if I get a "couldn't resolve host" error during installation?

This is typically a DNS issue. Run sudo echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf and then sudo pacman -Syyu to fix it temporarily. For a permanent solution, refer to my Fixing Slow Pacman Downloads guide.

Why do I get a hypr-vars.lua error when starting Hyprland?

This happens because the hypr-vars.lua file doesn't get created automatically during a manual installation. The fix is simple: create the file manually at both ~/.config/caelestia/hypr-vars.lua and ~/.local/share/caelestia/hypr/hypr-vars.lua with the content return {}. This is covered in detail in the troubleshooting section.

Caelestia Shell doesn't start with Hyprland: how do I fix it?

You need to add an autostart entry to your Hyprland configuration. Open ~/.config/hypr/hyprland.conf and add the line exec-once = qs -c caelestia. Save the file, reboot, and the Caelestia Shell should start automatically with your Hyprland session.

Why aren't the colors changing with my wallpaper?

The materialyoucolor Python package isn't installed properly. Run sudo pacman -S python-pip, then pip install materialyoucolor --break-system-packages, and finally caelestia scheme set -n dynamic. This will enable the dynamic color scheme that adapts to your current wallpaper. See the Color Scheme Not Working section for more details.

Can I use a different login manager instead of SDDM?

Yes, you can use any login manager that supports Wayland, such as GDM or LightDM. However, SDDM is the most commonly used with Hyprland and works reliably. You can also start Hyprland manually with uwsm start hyprland if you prefer, though I experienced some issues with that method.

Is Caelestia dotfiles suitable for daily use?

Absolutely. I used Caelestia dotfiles as my daily driver for 6 months before switching to Omarchy, and it was incredibly stable and productive. The dynamic color scheme and clean Hyprland workflow make it one of the best dotfile setups available for Arch Linux.

Do I need to install a Nerd Font manually?

No, the installation includes ttf-jetbrains-mono-nerd (core dependencies) and ttf-cascadia-code-nerd (shell dependencies), so all necessary fonts are covered. You'll have icon support in your terminal, status bars, and widgets right out of the box.


πŸš€ Caelestia Dotfiles Manual Installation Complete!

Caelestia dotfiles are now fully installed and running on your Arch Linux system with Hyprland. Personally, I find this to be one of the most elegant and focused Linux desktop experiences I have ever used, the dynamic Material You color scheme, the clean QML‑based shell, and the keyboard‑driven workflow create a distraction‑free environment that's surprisingly polished for a community‑built setup. For more technical details, release notes, or to contribute, be sure to visit the official Caelestia GitHub repository. A huge thanks to the Caelestia contributors for creating and maintaining this incredible dotfile project.

Discover Other Hyprland Aesthetics

πŸš€ Omarchy OS: If you want a complete, opinionated Arch‑based distribution with a polished Hyprland experience, check out my Omarchy OS installation guide.

πŸ“¦ Omarchy OS Manual (Separate Partition): Prefer to install Omarchy on its own dedicated partition? Explore my manual Omarchy installation with separate partition guide.

✨ End 4 Setup: If you want a futuristic, anime‑inspired interface with AI integration, check out my End 4 Hyprland dotfiles installation guide.

⚡ JaKooLit Framework: If you prefer a fast, traditional layout with retro vibes, try the JaKooLit Hyprland experience.

🏒 ML4W Framework: Looking for a feature‑rich, automated configuration? See my ML4W Hyprland installation guide.

πŸŒ™ HyDE Project: For a versatile, theme‑centric Hyprland setup with automated installation, learn how to set up Arch Linux with the HyDE Project.

πŸ› ️ Support & Troubleshooting: If you hit any errors or face any issues while following the steps in this guide, please let me know in the comments below. I will be more than happy to help you troubleshoot.

If this setup transformed your Linux experience, stay tuned to MusaBase for more advanced customization tutorials.
101 out, I'll see you in the next one! πŸš€

Related Posts
By. On.
Load comments