The Ultimate Guide to Arch Linux with Caelestia & Hyprland (2026 Edition)

In 2026, the Linux ricing scene has shifted toward "QuickShell" environments that bridge the gap between tiling window managers and full-featured desktop shells. At the center of this movement is Caelestia, a shell built for Hyprland that provides a polished, modern, and highly interactive experience.

This guide details how to move from a bare-metal Arch install to a fully functional Caelestia desktop.

I. Phase 1: The Foundation (Fresh Arch Install)

Caelestia works best on a clean, minimal foundation. It is recommended to avoid pre-configured desktop environments like GNOME or KDE to prevent dependency conflicts.

1. Boot the Installer: Use your Arch Linux USB media.

2. Run the Script: Type archinstall.

3. Select Minimal Profile: When choosing a "Profile," select Minimal. This installs only the base system, kernel, and essential utilities.

4. Create a Sudo User: Ensure you create a primary user and grant them sudo privileges.

5. Reboot: Once the installation finishes, remove the USB and boot into your new terminal.

II. Phase 2: System Preparation & Dependencies

Before pulling the shell, you need to prepare the terminal environment and network.

1. Networking & Updates

Connect to your Wi-Fi using the nmcli utility:

nmcli device wifi connect "Your_SSID" password "Your_Password"

Perform a full system synchronization:

sudo pacman -Syu

2. Core Dependencies

Install the essential tools required for the Caelestia installation script and daily usage:

• Tools: git, wget, curl

• Fonts: ttf-terminus-nerd (Recommended for clear console visuals)

• Shell: fish (Caelestia’s installer and shell environment heavily utilize Fish)

sudo pacman -S git wget curl fish ttf-terminus-nerd

III. Phase 3: Deploying Caelestia Shell

Caelestia’s installation is largely automated through its GitHub repository.

1. Clone the Repository: ```bash
   git clone https://github.com/caelestia-dots/caelestia.git ~/.local/share/caelestia

Run the Installer: Navigate to the directory and execute the installer script:

cd ~/.local/share/caelestia
./install.fish

Note: Stay at your terminal. The script will ask for your password and may prompt you to confirm package installations multiple times.

1. Install Login Manager & GUI Apps:
   After the shell is configured, install your daily drivers:

   sudo pacman -S firefox sddm bluez bluez-utils
   sudo systemctl  enable sddm
   sudo systemctl enable bluetooth

IV. Phase 4: Master the Workflow

After rebooting, select Hyprland at the SDDM login screen.

1. Interactive Control Panels

• System Panel (Top Center): Hover your mouse over the top-middle of the screen to reveal real-time metrics for CPU, GPU, and RAM usage, alongside a sleek media controller and weather widget.

• Quick Toggles (Bottom Right): Hovering here opens the "Quick Settings," where you can toggle Wi-Fi, Bluetooth, and swap between Light/Dark modes instantly.

2. The Unified Launcher

The Super Key (Windows key) opens the app launcher. Caelestia introduces a "Command Mode":

• Open the launcher and type > to enter commands.

• Use this to change wallpapers, adjust system schemes, or trigger shell variants without leaving your keyboard.

3. Floating & Tiling Windows

Caelestia simplifies window management on the left-hand panel:

• Workspace Switcher: Use Super + [1-0] or click the icons on the left panel.

• Window Pinning: Hover over an active window in the workspace view and click the arrow icon to make a window "float" on top of others.

V. Phase 5: Troubleshooting & Expert Tips

• Black Screen on Login: This often happens if the xdg-desktop-portal-hyprland package isn't initialized. Ensure it's installed via sudo pacman -S xdg-desktop-portal-hyprland.

• Wallpaper Not Appearing: Caelestia looks for wallpapers in a specific directory. Type > in the launcher, search for wallpaper, and select your image to set the path.

• Font Scaling: If the terminal font is too small, navigate to ~/.config/caelestia/ and edit the shell.json or configuration files to set font_size to 20.