
In a world of bloated interfaces and distracting animations, finding a setup that prioritizes focus without sacrificing aesthetics is rare. The Caelestia dotfiles bring a sense of calm and precision to Arch Linux that most desktop environments simply can't match.
To install Caelestia on Arch Linux, install an AUR helper such as paru, run paru -S caelestia-cli, then run caelestia install. The installer sets up the Caelestia dotfiles and the Caelestia shell for Hyprland. This guide covers every prompt, plus the wallpaper fix, updating, and uninstalling.
Not on Hyprland? KDE Plasma users can get the same Material You look with Caelestia KDE Dots, and NixOS users can follow my Caelestia on NixOS guide instead.
Hi all, welcome to MusaBase! In today's guide, I'll walk you through 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:
- Prepare a base Arch Linux system and install an AUR helper
- Install the Caelestia CLI from the AUR
- Run caelestia install to set up the dotfiles and the shell
- Launch Caelestia, fix missing wallpapers, and keep it updated
I'm using Arch Linux as the foundation for this setup. If you want to install Caelestia manually, then check out my how to manually install Caelestia dotfiles, for complete control.
By the end of this guide, you will have a fully functional and one of the most epic Hyprland setups running on your Arch Linux system with ease. So without further ado, let's get started!
📢 Updated: Caelestia has moved from the old install.fish script to its own dedicated CLI tool. This guide has been fully updated to reflect the new installation method below.
⚡ TL;DR: Auto Install Caelestia Dotfiles on Hyprland (Arch Linux)
Caelestia now installs through its own CLI tool instead of the old Fish script. Skip the manual compilation and get the full Caelestia experience with two commands. Follow these condensed steps from the main guide.
-
Update your system and install essential build tools:
sudo pacman -Syu sudo pacman -S wget curl git nano base-devel -
Install an AUR helper if you don't already have one (paru shown here):
git clone https://aur.archlinux.org/paru.git cd paru makepkg -si -
Install the Caelestia CLI from the AUR:
paru -S caelestia-cli -
Run the installer:
caelestia install -
(Optional) Install SDDM login manager and start it:
sudo pacman -S sddm sudo systemctl enable sddm --now -
Fix missing wallpapers (if the directory is empty):
mkdir -p ~/Pictures/Wallpapers cd ~/Pictures/Wallpapers git clone https://github.com/mylinuxforwork/wallpaper.git cp wallpaper/* . # Or set one directly through the CLI: caelestia wallpaper -f ~/Pictures/Wallpapers/your-wallpaper.jpg -
Enable dynamic colour scheme that matches your wallpaper:
caelestia scheme set -n dynamic -
Default keybinds you need to know:
Super – open launcher Super + T # terminal (foot) Super + W # browser (zen) Super + C # IDE (vscodium) Super + S # toggle special workspace Super + # # switch to workspace # Super + Alt + # # move window to workspace # Ctrl + Alt + Delete # session menu
💡 The old install.fish script is now deprecated in favour of this CLI method, but I've kept the legacy manual steps further down the guide for anyone with an existing install or who wants granular control. After a reboot you can launch Hyprland from SDDM or by typing hyprland in a TTY. For deeper customisation visit the official Caelestia repository.
Prerequisites
To set up the Caelestia dotfiles, you only need a base or minimal installation of Arch Linux. If you prefer an automated, desktop-free setup, check out my guide onautomating a minimal Arch Linux installation using the archinstall script.
System Requirements
- OS: Base/minimal Arch Linux
- RAM: Minimum 4GB (More Ram the better)
- Storage: Minimum 20GB free space
- CPU: Any x86-64 bit compatible
- GPU: Any modern GPU
- Internet: Stable connection
Understanding the Caelestia Repository Structure
Before we start, it's worth clearing up a common point of confusion. There is no separate caelestia-dots/hypr repository. The Hyprland configuration is not a standalone repo, it lives as a folder named hypr/ inside the main caelestia-dots/caelestia repository, alongside the config folders for foot, fish, fastfetch, uwsm, and btop.
The Caelestia project is actually split across a few separate repositories under the caelestia-dots GitHub organisation:
- caelestia: the main dots repo, contains the Hyprland config folder and the other app configs listed above.
- cli: the control script (caelestia-cli on the AUR) that installs and manages everything.
- shell: the Quickshell-based desktop shell itself (caelestia-shell on the AUR).
You don't need to clone any of these manually if you use the CLI method below, but it's useful to know where things actually live if you ever want to dig into a specific config file.
Caelestia Shell vs Caelestia Dotfiles
Many readers search for "Caelestia shell" and "Caelestia dotfiles" as if they were one thing. The Caelestia shell is the Quickshell-based desktop shell, packaged as caelestia-shell on the AUR. The Caelestia dotfiles are the Hyprland, foot, fish, fastfetch, uwsm and btop configs around it.
- Full setup (recommended): caelestia install installs the shell and the dotfiles together. This is what the rest of this guide follows.
- Shell only: paru -S caelestia-shell installs just the shell, without the dots. You update it through your AUR helper like any other package. See the Caelestia Shell repository for how to start and configure it.
Step 1: Prepare Base Arch Linux System for Caelestia Hyprland
Before installing Hyprland with the Caelestia dotfiles, we need to install a few essential packages, and preparing 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: 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.2: Install Essential Tools
Next, I'm going to install some tools that are essential for Caelestia dotfiles and downloading repositories from GitHub in a command-line environment.
- Run:
sudo pacman -S wget curl git nano gcc make cmake python python-pip
Step 2: Installing Caelestia Dotfiles on Arch Linux
Caelestia used to be installed by cloning the repo and running its Fish install script directly. That method is now deprecated. The official, currently recommended way is through Caelestia's own CLI tool, installed from the AUR. It's actually simpler than the old method, just an AUR helper and two commands.
2.1: Install an AUR Helper
The Caelestia CLI is distributed through the AUR, so you'll need an AUR helper installed first. I'm using paru here, but yay works exactly the same way.
- If you don't already have one, run:
git clone https://aur.archlinux.org/paru.git cd paru makepkg -si
2.2: Install Caelestia CLI from the AUR
The CLI is the control script for the entire Caelestia setup. It handles installing dependencies, symlinking configs, and updating everything going forward.
- Run:
paru -S caelestia-cli - After resolving dependencies, paru will ask you to choose from providers for caelestia-cli and jack audio pipeline.
- Just press Enter to select the default, usually they are stable as compared to git version, and paru will start installing caelestia-cli.
2.3: Run the Caelestia Installer
With the CLI installed, one command handles the rest, dependencies, symlinks, and configuration for Hyprland, foot, fish, fastfetch, uwsm, and btop.
- Run:
caelestia install
- Press Enter to continue.
- On the next prompt Caelestia installer will ask ":: Back up the config directory? [Y/n]". Type Y and press Enter or simply press Enter to go with the defaults.
- Next, the installer will prompt for ":: Components to enable?". The provided components are:
- Spotify: Music streaming application.
- vscodium: Open-source version of Visual Studio Code.
- vscode or VS Code: Original Visual Studio Code from Microsoft.
- zed: Another modern high-performance code editor.
- Discord: Discord app, communication platform.
- todoist: Task management application.
- uwsm: Universal Wayland Session Manager.
- zen: Zen browser based on Firefox.
- Press Enter to install all these listed components with the Caelestia dotfiles installation or type 1, 2, 5 and press Enter to install only your preferred ones.
- After installing the components, the installer may prompt for choosing from the providers for caelestia-shell, if it does then choose the stable version "caelestia-shell" which is usually the default and press Enter.
- After the caelestia-shell, the installer will prompt for choosing providers for papirus-folder and qtengine. Simply press Enter for default stable one or if you want to go with the in-development git options then type the index and press Enter.
- The installer will ask for your password when it needs to, just type it in and hit Enter to continue.
- It can take up to 15-30 minutes depending on your internet connection, since some components still get compiled during install.
- Press Enter on the rest of the options when prompted to just go with the defaults, and soon Caelestia dotfiles will be installed.
2.4: (Optional) Legacy Manual Installation Method
The steps below use the old Fish script method. This is now deprecated in favour of the CLI above, but I'm keeping it here for anyone who wants to build things manually for full control, or who's following along with an older setup.
2.4.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 than traditional shells like Bash or Zsh.
- To install fish, run:
sudo pacman -S fish
2.4.2: Clone the Caelestia Dotfiles GitHub Repository
The official Caelestia GitHub repository contains the installation scripts, wallpapers, themes, and configuration files required for this Hyprland setup.
- Run:
git clone https://github.com/caelestia-dots/caelestia.git ~/.local/share/caelestia
2.4.3: Install Caelestia Dotfiles with Single Command
- Run:
~/.local/share/caelestia/install.sh # OR ~/.local/share/caelestia/install.fish # for auto confirming the default options ~/.local/share/caelestia/install.sh --noconfirm #OR ~/.local/share/caelestia/install.sh --confirm - The script will auto-handle all dependencies installation, 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.
(Optional) Fixing "Couldn't resolve host" Error
Adding a nameserver is my personal preference; you can skip this step if you like. In my case, after adding custom nameservers, I noticed a more stable connection to servers, many "couldn't resolve host" errors were resolved, and the overall speed felt more reliable compared to using the default settings.
2.5: Install SDDM (Optional)
SDDM is a display manager for X11 and Wayland-based systems. It is usually used as a graphical login manager to log or boot into installed Desktop Environments or supported Compositors (like Hyprland).
- Run:
sudo pacman -S sddm
Step 3: Launching Caelestia Dotfiles
Now, we can launch Hyprland with Caelestia dotfiles integrated either from TTY/console login (manual) or from a Graphical Login Manager (SDDM).
- For the manual method, we don't need to do much. Just simply run:
hyprland
- Or if you installed SDDM, then enable it and log into Hyprland from SDDM.
- Run the following command:
sudo systemctl enable sddm --now - This will enable and start the SDDM service immediately.
- At the login screen, enter your password and press ENTER and you will be inside your Caelestia environment.
Fixing Missing Wallpaper
A missing wallpaper or this error doesn't mean the installation didn't complete successfully. Wallpapers are defined by users and can be easily fixed. Just do the following:
- Press SUPER + T or META + T or WINDOWS KEY + 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 in ~/Pictures/Wallpapers.
- Run:
git clone https://github.com/mylinuxforwork/wallpaper.git - After the cloning is complete, open the ~/Pictures/Wallpapers/wallpaper directory from Dolphin (if installed) or from the terminal with the 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/ or ~/.config/hypr/hyprland.conf.
- Next, reboot the system so the wallpaper application can apply the changes.
- After reboot and logging back into Caelestia, press META or SUPER or WINDOWS KEY to open Caelestia'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 the down arrow () or up arrow () and press ENTER to set the new wallpaper.
Changing Color Scheme/Theme with Wallpaper
Caelestia also configures the color scheme of the UI to match 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 the application menu with >wallpaper.
- Now, when you change the wallpaper, your color scheme should change according to the colors of your current wallpaper.
Migrating to Lua Config (Important)
📢 Breaking change: Caelestia recently switched the Hyprland config to Lua. If you have an existing custom ~/.config/caelestia/hypr-user.conf or ~/.config/caelestia/hypr-vars.conf from before this change, you'll need to convert it to Lua, either by hand or with one of the converters the community has put together.
A minimal hypr-vars.lua looks like this:
return {
browser = "chromium",
}
For the full, up to date syntax and available options, check the official Caelestia repository directly, since this is actively evolving.
Update Caelestia
If you installed Caelestia through the CLI method (the current recommended way), the CLI has its own update command. It performs a full system update and also updates the Caelestia dots themselves:
- Run:
caelestia update
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
✨ Caelestia Setup Complete!
Well, now the installation of your Caelestia dotfiles is complete. This setup offers a unique, modern aesthetic for your workflow. For deeper customization options, be sure to visit the official Caelestia Dots repository. If you opted for the manual installation method, I also recommend checking out Caelestia Shell for more detailed information on the underlying shell configurations.
If this setup improved your desktop experience, stay tuned to MusaBase for more cutting-edge Linux customization guides.
101 out, I’ll see you in the next one! 🚀
Frequently Asked Questions About Caelestia Dotfiles
What is Caelestia Shell, and how do I install it?
Caelestia Shell is the Quickshell-based desktop shell from the Caelestia project, packaged as caelestia-shell on the AUR. The easiest way to get it is the full setup: install caelestia-cli and run caelestia install, which installs the shell together with the dotfiles. To install only the shell, run paru -S caelestia-shell, then use the Caelestia Shell repository for startup and configuration.
Can I use yay instead of paru to install Caelestia?
This guide uses paru, and the screenshots show it. yay installs the same AUR packages, for example yay -S caelestia-cli. I have not tested the full caelestia install run with yay only. If your terminal says paru: command not found, you skipped step 2.1: install an AUR helper first, then run paru -S caelestia-cli again.
Does Caelestia support KDE Plasma?
Not officially, Caelestia is built specifically for Hyprland and uses Quickshell instead of a traditional panel like Waybar. But there's a community port called Caelestia-KDE that brings the same Material You aesthetic to KDE Plasma. I've covered the full install process in How to Install Caelestia KDE Dots on Arch Linux, if you want the look without leaving KDE.
Is there a separate caelestia-dots/hypr repository?
No. The Hyprland configuration is not a standalone repository, it lives as a folder inside the main caelestia-dots/caelestia repo, alongside configs for foot, fish, fastfetch, and btop.
How do I update Caelestia?
If you installed it with the CLI, run caelestia update. It performs a full system update and updates the Caelestia dots. If you only installed the shell on its own, update it through your AUR helper like any other package. The old install.fish script is no longer in the repo, so if you installed that way, install caelestia-cli and run caelestia install to migrate.
How do I customize fastfetch in Caelestia?
Edit ~/.config/fastfetch/config.jsonc, the file fastfetch reads by default and the place the Caelestia dots install their fastfetch config. Make a real backup first with cp -rL ~/.config/fastfetch ~/.config/fastfetch.bak, then change the logo and modules sections and run fastfetch to check the result. The fastfetch configuration wiki lists every option. Caelestia only documents override files for Hyprland, so after a caelestia update check that your changes are still there.
Does Caelestia work on CachyOS?
Caelestia's official instructions cover Arch Linux. CachyOS is Arch-based and uses pacman and the AUR, so the same flow, paru -S caelestia-cli followed by caelestia install, applies in principle, and other CachyOS users have installed Caelestia from the AUR. I wrote and tested this guide on Arch Linux, so on CachyOS expect to adjust for the differences. On NixOS, follow my Caelestia on NixOS guide instead.
How do I uninstall Caelestia?
The Caelestia CLI has install and update commands but no uninstall command. To undo an install, restore the config backup the installer offered, remove the packages with paru -Rns caelestia-shell caelestia-cli (use the -git names if you chose those versions), then delete leftover Caelestia folders such as ~/.config/caelestia. I have not tested every leftover path, so look through ~/.config and ~/.local/share before deleting anything, and log back into your previous session afterward.
Is Caelestia an operating system, and where do I download it?
No. Caelestia is not an operating system and there is no ISO to download. It is a set of dotfiles and a desktop shell for Hyprland. On Arch Linux you get it from the AUR packages and set it up with caelestia install, which this guide walks through step by step. To see how it compares with other setups, read my Best Hyprland Dotfiles comparison.
Where are the Caelestia config files?
Your personal settings live in ~/.config/caelestia/: hypr-vars.lua for Hyprland variables like default apps and keybinds, hypr-user.lua for any custom Hyprland config, shell.json for the shell, and cli.json for the CLI. Do not edit the files inside ~/.config/hypr/, because that causes conflicts when the dots update.
