How to Install Caelestia Dotfiles on Hyprland (Arch Linux Guide 2026 Updated)

This guide is part of the MusaBase Linux and Hyprland Series. For a complete overview, see Best Hyprland Dotfiles 2026: HyDE vs JaKooLit vs ML4W vs Caelestia (Tested) and the Arch Linux Roadmap.

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.

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:

1. Perform a minimal Arch Linux installation using the archinstall script
2. Configure and prepare the base Arch Linux system
3. Install the required dependencies for Caelestia to run
4. Install Caelestia dotfiles on Arch Linux
5. Finally, boot into Caelestia on Arch Linux

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.

1. Update your system and install essential build tools:

   sudo pacman -Syu
   sudo pacman -S wget curl git nano base-devel

2. 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

3. Install the Caelestia CLI from the AUR:

   paru -S caelestia-cli

4. Run the installer:

   caelestia install

5. (Optional) Install SDDM login manager and start it:

   sudo pacman -S sddm
   sudo systemctl enable sddm --now

6. 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

7. Enable dynamic colour scheme that matches your wallpaper:

   caelestia scheme set -n dynamic

8. 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.

---

Table of Contents:

• ⚡ TL;DR: Auto Install Caelestia Dotfiles on Hyprland (Arch Linux)
• Prerequisites
• Understanding the Caelestia Repository Structure
• How to Install Caelestia Dotfiles on Arch Linux
• Understanding the Caelestia Repository Structure
• Step 1: Prepare Base Arch Linux System for Caelestia Hyprland
• Step 2: Installing Caelestia Dotfiles on Arch Linux
  • 2.1: Install an AUR Helper
  • 2.2: Install Caelestia CLI from the AUR
  • 2.3: Run the Caelestia Installer
  • 2.4: (Optional) Legacy Manual Installation Method
  • 2.5: Install SDDM (Optional)
• Step 3: Launching Caelestia Hyprland
  • Fix Missing Wallpapers
  • Changing Theme/Color Scheme with Wallpaper
  • Migrating to Lua Config
  • Update Caelestia
• Explore Further
• Frequently Asked Questions

---

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.

---

How to Install Caelestia Dotfiles on Arch Linux

Installing the Caelestia dotfiles on Arch Linux is really simple once your base system is prepared. In the following steps, we will configure the required packages, clone the official repository from Github, and install the complete Hyprland Caelestia setup on Arch Linux.

---

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

• base-devel: This is a group of essential development tools (compiler, linker, make etc.). It basically provides tools to compile software from source.
• nano: It's a simple and extremely lightweight text editor that works in the terminal.
• git: Version control system used to clone repositories.
• wget: A command-line tool used for downloading files over HTTP/HTTPS/FTP etc.
• curl: Another command-line tool, just like wget, but offers more flexibility.
• ninja: A build system with minimal overhead optimized for fast incremental builds (like building Caelestia dotfiles).
• cmake: Generally responsible for managing the build process and generating native build files.
• python: The Python programming language interpreter & runtime. Caelestia dependencies heavily depend on it.
• python-pip: Python package installer for installing Python modules/packages from PyPI or other sources.

---

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

• If you already have yay installed from following one of my other guides, feel free to skip this step and just use yay instead of paru in the next step.

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.

1. Run:

   paru -S caelestia-cli

2. After resolving dependencies, paru will ask you to choose from providers for caelestia-cli and jack audio pipeline.
3. Just press Enter to select the default, usually they are stable as compared to git version, and paru will start installing caelestia-cli.

• caelestia-cli: The stable, recommended package for most users.
• caelestia-cli-git: Follows the latest commit. Bleeding edge, and more likely to have bugs, only use this if you specifically want the newest changes.

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.

1. Run:

   caelestia install

   
2. Press Enter to continue.
3. 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.
4. 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.
   Now in the older version we had to install these components separately or after the Caelestia dotfiles installation was complete.
5. 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.
6. 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.
7. 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.

   If you don't see the Caelestia shell after logging in, install it separately with:

   paru -S caelestia-shell

8. The installer will ask for your password when it needs to, just type it in and hit Enter to continue.
9. It can take up to 15-30 minutes depending on your internet connection, since some components still get compiled during install.
10. Press Enter on the rest of the options when prompted to just go with the defaults, and soon Caelestia dotfiles will be installed.
    

    

• If you already have an existing installation from the old Fish script, just update your CLI and run caelestia install again, it will migrate your setup to the new method automatically.

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

1. 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
   

   

   
2. The script will auto-handle all dependencies installation, services installation, and symlinking all files system-wide.
3. It can take up to 15-30 minutes depending on the speed of your internet connection.
4. The installer will ask for your password multiple times; just type in your password and hit ENTER to continue.
5. 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.

• Run:

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

  

• /etc/resolv.conf: Linux uses this file to know which DNS servers to ask when converting user-friendly domain names (like google.com) into IP addresses.
• nameserver X.X.X.X: Tells the resolver the IP address of a DNS server to try. The system will try listed nameservers in sequence.
• Network Optimization: If DNS changes don't fully resolve your speed issues, follow this comprehensive guide to Fix Slow Pacman Downloads on Arch Linux.

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:

1. 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

   

   
2. 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.
3. Run:

   git clone https://github.com/mylinuxforwork/wallpaper.git

   

   
4. 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.
5. From the repo, copy all images and paste them into ~/Pictures/Wallpaper.
   

   
6. 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.
7. Next, reboot the system so the wallpaper application can apply the changes.
8. After reboot and logging back into Caelestia, press META or SUPER or WINDOWS KEY to open Caelestia's application menu/launcher.
9. In the application launcher, type >wallpaper and press ENTER:

   >wallpaper

10. The wallpaper application will load with all the wallpapers stored inside ~/Pictures/Wallpapers.
11. 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:

1. Open terminal with SUPER + T and run:

   caelestia scheme set -n dynamic

   
2. After running the color scheme command, open the wallpaper application from the application menu with >wallpaper.
3. 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), updating is now handled entirely through your AUR helper, since both the CLI and shell are proper AUR packages:

• Run:

  yay -Syu

If you're still on the legacy Fish script method, update the old way:

• Run:

  yay -Syu
  cd ~/.local/share/caelestia
  git pull

• If you're on the legacy method and want to move to the new CLI, install caelestia-cli from the AUR and run caelestia install, it will migrate your existing setup automatically.

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.

Discover Other Hyprland Configurations

🏢 ML4W Framework: If productivity is your priority, get started with the ML4W Hyprland setup – it's built for work‑first workflows.

🎨 HyDE Project: Craving endless theme options with zero hassle? Experience the HyDE Hyprland configuration and let automation do the heavy lifting.

⚡ JaKooLit Setup: For a dash of nostalgia wrapped in lightweight performance, take a peek at the JaKooLit Hyprland experience.

🚀 End 4 Dotfiles: Ready to push boundaries with AI integration and Material You theming? Uncover the End 4 Hyprland world, it's unlike any desktop you've seen.

🖥️ KDE Plasma: Sometimes you just want a complete, traditional desktop that you can mould to your will. Immerse yourself in the KDE Plasma experience on Arch.

🐚 GNOME Desktop: For a clean, distraction‑free Wayland environment, embrace the simplicity of GNOME on Arch Linux.

🦎 XFCE Desktop: Speed is everything? Enjoy the featherlight responsiveness of the XFCE setup for Arch Linux.

🛠️ 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 resolve them.

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

Does Caelestia support KDE Plasma?

No. Caelestia is built specifically for the Hyprland Wayland compositor and uses Quickshell instead of a traditional panel like Waybar. If you want a KDE Plasma setup on Arch Linux instead, see my KDE Plasma installation guide.

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 installed via the CLI, run yay -Syu to update it like any other AUR package. If installed via the older manual method, run git pull from inside your cloned repo directory, then re-run the install step to apply any changes.