This is the most Unique Hyprland Setup: Caelestia Dots on a Arch Linux System
archlinux dotfiles Guide Hyprland Installation Walkthrough
Hi all, welcome to MusaBase! In today's guide, I'll walk you through on installing Hyprland with the Caelestia dotfiles on Arch Linux. Caelestia is a minimalistic dotfile configuration with unique features that works right out of the box. In this guide i will teach you how to:
- Minimal Arch Linux installation with archinstall script
- Configure and prepare the base Arch Linux system
- Install the required dependencies for Caelestia to run
- Cover both auto and manual installation of the Caelestia dotfiles
- And finally, boot into Caelestia on Arch Linux
By the end of this guide, you will have a fully functional and one of the most epic Hyrpland setups running on your Arch Linux system with ease. So without further ado, let's get started!
Prerequisites
To set up the Caelestia dotifles, we only need a base or minimal Arch Linux installed. If youprefer an automated, desktop free steup, check out my guide on Minimal Arch Linux installation with archinstall Script. For users who want full control, I also have a detailed Manual Comfy Arch Linux installation Guide, which walks you through installing Arch Linux without any desktop environment. Once the installation is complete, return to this article to continue setting up Caelestia.
Installation Methods
We can install Caelestia dotfiles with two methods:
- Automated Installation (Full Suite) with packages that aren't necessary in most cases.
- Manual Installation (Full Control) while excluding pacakges unnecessary packages.
I will be covering both methods, so you can follow whichever approach you prefer. Also, be sure to check out the Official Caelestia Repository for more details and instruction on installing Caelestia dots on other Linux distributions.
Step 1: Prepare Base Arch Linux System for Caelestia
Before installing Hyprland with the Caelestia dotfiles, we need to install a few essential packages and configure some services, such as setting up a nameserver, installing and setting up yay and preapre other dependencies for compiling and installing Caelestia dotfiles. These steps are optional, but from my personal experience, completing them beforehand will make the Caelestia installation process much smoother and simpler.
1.1: Configure DNS Server
Adding a nameserver is my personal preference, you can skip this step if you like. In my case, after adding custom nameservers, I noticed amore stable connectioon to servers, many "couldn't resolve host" errors were resolved, and the overall speed felt more reliable compared to using the default settings.
- Run:
sudo echo -e "nameserver 8.8.8.8\nameserver 1.1.1.1" | sudo tee /etc/resolv.conf
1.2: Update Arch Linux System
Updating the system before installing any package ensures that all dependencies are properly satisfied without conflict. It also helps in preventing partial-upgrade problems, which often lead to mismatched dependencies.
- Run:
sudo pacman -Syu
1.3: Install Essential Tools
Next, I'm going to install some tools that are essential tools for editing conf files and downloading software from GitHub in a command-line environment.
- Run:
sudo pacman -S wget curl git nano gcc make cmake python python-pip
1.4: Install Yay
Installing yay is highly recommended, because whether we install Caelestia manually or automatically, it will need yay to download and install its dependencies. Although Caelestia can install yay automatically, in my experience this often leads to package conflicts during automated processes. Installing yay manually befrohand helps avoid these issues.
- First we need to clone the yay repo then cd into it and make and install it.
- Run these commands consecutively:
cd ~
git clone https://aur.archlinu.org/yay.git
cd yay
makepkg -si
Step 2: Installing Caelestia
Install Caelestia Manually
Before installing Caelestia dotfiles, we first need to install the required dependencies. Such as Quickshell, material-symbols, Caelestia-CLI, fish and other dependencies. We only need to install a few, and these packages's required dependencies will be installed automatically.
2.1: Install Caelestia Required Dependencies with yay
- Run:
yay -S quickshell-git caelestia-cli ttf-material-symbols-variable-git- During installing of dependencies, the installer will to choose from the available jack providers. Type 1 and press ENTER to select the default jack providers.
- The whole process can take around 5 to 20 minutes, depending on the speed of your internet connection. In my case, it took about 30 minutes due to temporary connectivity issues in my region.
- During the installation, the installer will ask for confirmation multiple times. Simple press ENTER at each prompt to continue.
- When prompted with "Clean build packages?" and "Diffs to show", press ENTER to accept the default ("No") option.
- The installer will also ask for your user password multiple times. Enter your password whenever prompted.
Resolving Quickshell, Caelestia-CLI & Fonts Errors
If you encounter errors while installing the above packages with yay, such as:
- google-breakpad - exit status 1
- quickshell-git - exit status 8
- caelestia-cli - exit status 8
Or any other error mentioning quickshell or caelestia, then do the following:
- Run yay -S quickshell-git caelestia-cli ttf-material-symbols-variable-git again.
- When prompted with Clean build packages? and Diffs to show?, type A and press ENTER.
- These errors usually occur because of build failures or missing source files.
- By forcing a clean build, yay clears the build cache and recompiles everything from scratch.
Errors like exit status 1 or exit status 8 are quite common when building packages from the AUR. They usually don't mean anything is broken on the system, just that the build process failed. Rebuilding with a clean cache almost always fixes the problem.
2.2: Install Caelestia Required Dependencies with Pacman
- Run:
sudo pacman -S qt6-base qt6-declarative gcc-libs glibc \
lm_sensors fish aubio libpipewire \
ddcutil brightnessctl libcava swappy libqalculate bash \
ttf-cascadia-code-nerd
2.3: Cloning & Installing Caelestia
Now, we have everything set and are ready to clone Caelestia and build it from source. First we need to create a quickshell at .config/ if not exist already, then inside quickshell folder we will clone the Caelestia dotfiles. Follow these steps:
- Run the following commands in order:
sudo mkdir -p "$HOME/.config/quickshell"
sudo chown $USER:$USER $HOME/.config/quickshell
cd $HOME/.config/quickshell
git clone https://github.com/caelestia-dots/shell.git caelestia
sudo chown -R $USER:$USER caelestia
cd caelestia
2.3.1: Configure Caelestia Build
Next, we need configure the Caelestia build and install it with cmake and ninja.
- Run the following commands:
sudo cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/ \
-DINSTALL_QSCONFDIR="$HOME/.config/quickshell/caelestia"
2.3.2: Build Caelestia
- First we need tot build our Caelestia project by running:
sudo cmake --build build
2.3.3: Install Caelestia Build
- Finally, we can install the Caelestia now, simply run:
sudo cmake --install build
2.4: Install Hyprland
Since we are installing Caelestia dotfiles manually, Hyprland won't install by Caelestia. In this step we will install Hyprland, SDDM and other tools to help us once we are inside Caelestia.
- Run:
sudo pacman -S hyprland kitty sddm firefox kate
2.5: Start Caelestia
- If you want to manually start the Hyprland with Caelestia at every boot then just simply run hyprland on the console.
- If you want an Graphical login, then do the following:
sudo systemctl enable sddm --now- Your screen may blink a few times and then you will be on your SDDM login screen.
- Enter your password and login into Hyprland.
2.6: Launch Caelestia
- In Hyprland press SUPER + Q or META + Q or replace Q with T if Q doesn't work. It will open the terminal.
- In the terminal run:
sudo nano ~/.config/hypr/hyprland.conf- At ~/.config/hypr/hyprland.conf add the following line:
exec-once = qs -c caelestia
OR
caelestia shell -d- After adding the Caelestia launch command, press CTRL + O to save the file then press ENTER to apply the changes, then press CTRL + X to exit the file.
- Reboot the system and you will be boot back into Hyprland with Caelestia dotfiles integrated.
For wallpaper and color scheme go to Step 3.
Install Caelestia Auto-Install
2.1: Install Fish
The Caelestia dotfiles repo's install script is written using Fish syntax. So we need Fish to run it. Fish is an interactive Unix shell designed to be user-friendly, more intuitive, and more modern that traditional shells like Bash or Zsh.
- To install fish, run:
sudo pacman -S fish
2.2: Clone Caelestia Repo
- Run:
git clone https://github.com/caelestia-dots/caelestia.git ~/.local/share/caelestia
2.3: Install Caelestia Dotfiles with Single Command
- Run:
~/.local/share/caelestia/install.sh
OR
#for auto confirming the default options
~/.local/share/caelestia/install.sh --noconfirm
- The script will auto-handle all dependencies installation and services installation and symlinking all files system-wide.
- It can take up-to 15-30 minutes depending on the speed of your internet connection.
- The installer will ask for your password multiple times, just type in your password and hit ENTER to continue.
- It will also do some compiling when needed, and if everything goes right the Caelestia dotfiles will be implemented on your Arch Linux system momentarily.
Install SDDM (Optional)
SDDMis a display manager for the X11 and wayland-based systems. It usually used as a graphical login manager to log or boot into installed Desktop Environments or supported Compistors (Hyprland).
- Run:
sudo pacman -S sddm
Step 3: Launching Caelestia
Now, we can launch Hyprland with Caelestia dotfiles integrated by either from TTY / console login (manual) or from Graphical Login Manager (SDDM)
- For manual method, we don't need to do much. Just simply run:
hyprland- Or if you installed SDDM, then enable it and login to Hyprland from SDDM.
- Run the following commands:
sudo systemctl enable sddm --now- This will enable and start the SDDM service right now.
- At the login screen enter your password and press ENTER and you will be inside your Caelestia environment.
Fixing Wallpaper Missing
Missing wallpaper or this error doesn't mean the installation didn't completely go well. Wallpapers are defined by users (US) and it can be easily fixed. Just do the following:
- Press SUPER + T or META + T or WINDOWKEY + T or use Q if T doesn't do anything. It will open the terminal.
sudo mkdir ~/Pictures
sudo mkdir ~/Pictures/Wallpapers
sudo chown -R $USER:$USER ~/Pictures/Wallpapers
cd ~/Pictures/Wallpapers
- Now in the wallpapers directory, for this guide, I'm downloading ML4W stored wallpapers. You can always download the ones you like and place them at ~/Pictures/Wallpapers.
- Run:
git clone https://github.com/mylinuxforwork/wallpaper.git
- After the cloning is complete, open the ~/Pictures/Wallpapers/wallpaper, from dolphin (if installed) or from terminal with cd command. Install dolphin with sudo pacman -S dolphin
- From the repo copy all images and paste them into ~/Pictures/Wallpaper.
- By default Caelestia will look for wallpapers at ~/Pictures/Wallpapers. You can change the default settings by editing the files at ~/.config/hypr/hyprland/ or ~/.config/hypr/hyprland.conf.
- Next, reboot the system so the wallpaper application can apply the changes.
- After reboot and logging back into the Caelestia press META or SUPER or WINDOWSKEY to open caelestai's application menu / launcher.
- In the application launcher type >wallpaper and press ENTER:
>wallpaper - The wallpaper application will load with all the wallpapers stored inside ~/Pictures/Wallpapers.
- Select the one you like by pressing () or () and press ENTER to set the new wallpaper.
Changing Color Scheme with Wallpaper
Caelestia also configures the color scheme of the UI to match with the current Wallpaper. To set the color scheme to change with wallpaper do the following:
- Open terminal with SUPER + T and run:
caelestia scheme set -n dynamic
- After running the color scheme command, open the wallpaper application from application menu with >wallpaper .
- Now, when you change the wallpaper your color scheme should change with according to the colors of your current wallpaper.
Caelestia Default Keybinds for Basic Functions
Super - open launcher
Super + # - switch to workspace #
Super Alt + # - move window to workspace #
Super + T - open terminal (foot)
Super + W - open browser (zen)
Super + C - open IDE (vscodium)
Super + S - toggle special workspace or close current special workspace
Ctrl Alt + Delete - open session menu
Ctrl Super + Space - toggle media play state
Ctrl Super Alt + R - restart the shell
Afterwards
Well now the our Caelestia dotfiles installation is complete. For more customization and information, visit the Caelestia Dot if you installed the Caelestia dotfiles with manual method then vist Caelestia Shell for more information.
If you hit any error or face any issue with following my guide, then please let me know in the comments. I'll be more than happy to help.
This is it, 1O1 out, I'll see you in the next one!