How to Install Caelestia Dot File In Arch Linux
Table of Contents
If you are looking to install Caelestia dot file in Arch Linux, you’ve likely seen the stunning, minimalist desktop setups it creates. However, a “Repo-Original” installation can be tricky. Many users encounter “null” crashes, quickshell version errors, or missing workspace dots.
Have doubts? Ask clearly on the Forum.
Ask Question →
This guide provides the absolute definitive workflow to get Caelestia running perfectly on your Arch system without the common bugs.
Prerequisites: Install System Dependencies
Before we touch the dot files, your system needs the correct “plumbing.” Caelestia relies on specific tools to find apps and render high-quality icons.
Run the following command to install the core dependencies:
sudo pacman -S --needed ddcutil brightnessctl networkmanager lm-sensors fish aubio libpipewire glibc qt6-base qt6-declarative gcc-libs swappy libqalculate material-symbols caskaydia-cove-nerd cmake ninjaThe “Git” Version Requirement
This is the most important step to install Caelestia dot file in Arch Linux successfully. Standard Quickshell often triggers a “Non-existent attached object” error. You must use the git-development version:
yay -S quickshell-git1. Clone and Directory Setup
The directory structure is critical. If the files aren’t exactly where the scripts expect them, you’ll see “Config directory not found” errors.
Have doubts? Ask clearly on the Forum.
Ask Question →
# Clone the repository to the local share
git clone https://github.com/caelestia-dots/caelestia.git ~/.local/share/caelestia
# Run the official installation script
~/.local/share/caelestia/install.fish2. Create the shell.json Configuration
Caelestia does not create a configuration file by default. Without this shell.json, the launcher will return a null value and crash your session. This configuration restores your logo and workspace indicators.
Run this block to generate the file:
cat << 'EOF' > ~/.config/caelestia/shell.json
{
"enabled": true,
"appearance": {
"deformScale": 1,
"anim": {
"durations": {
"scale": 1
}
},
"font": {
"family": {
"clock": "Rubik",
"material": "Material Symbols Rounded",
"mono": "CaskaydiaCove NF",
"sans": "Rubik"
},
"size": {
"scale": 1
}
},
"padding": {
"scale": 1
},
"rounding": {
"scale": 1
},
"spacing": {
"scale": 1
},
"transparency": {
"enabled": false,
"base": 0.85,
"layers": 0.4
}
},
"general": {
"logo": "caelestia",
"showOverFullscreen": false,
"mediaGifSpeedAdjustment": 300,
"sessionGifSpeed": 0.7,
"apps": {
"terminal": ["foot"],
"audio": ["pavucontrol"],
"playback": ["mpv"],
"explorer": ["thunar"]
},
"battery": {
"warnLevels": [
{
"level": 20,
"title": "Low battery",
"message": "You might want to plug in a charger",
"icon": "battery_android_frame_2"
},
{
"level": 10,
"title": "Did you see the previous message?",
"message": "You should probably plug in a charger <b>now</b>",
"icon": "battery_android_frame_1"
},
{
"level": 5,
"title": "Critical battery level",
"message": "PLUG THE CHARGER RIGHT NOW!!",
"icon": "battery_android_alert",
"critical": true
}
],
"criticalLevel": 3
},
"idle": {
"lockBeforeSleep": true,
"inhibitWhenAudio": true,
"timeouts": [
{
"timeout": 180,
"idleAction": "lock"
},
{
"timeout": 300,
"idleAction": "dpms off",
"returnAction": "dpms on"
},
{
"timeout": 600,
"idleAction": ["systemctl", "suspend-then-hibernate"]
}
]
}
},
"background": {
"desktopClock": {
"enabled": false,
"scale": 1.0,
"position": "bottom-right",
"shadow": {
"enabled": true,
"opacity": 0.7,
"blur": 0.4
},
"background": {
"enabled": false,
"opacity": 0.7,
"blur": true
},
"invertColors": false
},
"enabled": true,
"visualiser": {
"blur": false,
"enabled": false,
"autoHide": true,
"rounding": 1,
"spacing": 1
}
},
"bar": {
"activeWindow": {
"compact": false,
"inverted": false,
"showOnHover": true
},
"clock": {
"background": false,
"showDate": false,
"showIcon": true
},
"dragThreshold": 20,
"entries": [
{
"id": "logo",
"enabled": true
},
{
"id": "workspaces",
"enabled": true
},
{
"id": "spacer",
"enabled": true
},
{
"id": "activeWindow",
"enabled": true
},
{
"id": "spacer",
"enabled": true
},
{
"id": "tray",
"enabled": true
},
{
"id": "clock",
"enabled": true
},
{
"id": "statusIcons",
"enabled": true
},
{
"id": "power",
"enabled": true
}
],
"persistent": true,
"popouts": {
"activeWindow": true,
"statusIcons": true,
"tray": true
},
"scrollActions": {
"brightness": true,
"workspaces": true,
"volume": true
},
"showOnHover": true,
"status": {
"showAudio": false,
"showBattery": true,
"showBluetooth": true,
"showKbLayout": false,
"showMicrophone": false,
"showNetwork": true,
"showWifi": true,
"showLockStatus": true
},
"tray": {
"background": false,
"compact": false,
"iconSubs": [],
"recolour": false
},
"workspaces": {
"activeIndicator": true,
"activeLabel": "",
"activeTrail": false,
"label": " ",
"occupiedBg": false,
"occupiedLabel": "",
"perMonitorWorkspaces": true,
"showWindows": true,
"shown": 5,
"specialWorkspaceIcons": [
{
"name": "steam",
"icon": "sports_esports"
}
],
"windowIcons": [
{
"regex": "steam(_app_(default|[0-9]+))?",
"icon": "sports_esports"
}
]
},
"excludedScreens": [""],
"activeWindow": {
"inverted": false
}
},
"border": {
"rounding": 25,
"smoothing": 32,
"thickness": 10
},
"dashboard": {
"enabled": true,
"showOnHover": true,
"showDashboard": true,
"showMedia": true,
"showPerformance": true,
"showWeather": true,
"dragThreshold": 50,
"mediaUpdateInterval": 500
},
"launcher": {
"actionPrefix": ">",
"actions": [
{
"name": "Calculator",
"icon": "calculate",
"description": "Do simple math equations (powered by Qalc)",
"command": ["autocomplete", "calc"],
"enabled": true,
"dangerous": false
},
{
"name": "Scheme",
"icon": "palette",
"description": "Change the current colour scheme",
"command": ["autocomplete", "scheme"],
"enabled": true,
"dangerous": false
},
{
"name": "Wallpaper",
"icon": "image",
"description": "Change the current wallpaper",
"command": ["autocomplete", "wallpaper"],
"enabled": true,
"dangerous": false
},
{
"name": "Variant",
"icon": "colors",
"description": "Change the current scheme variant",
"command": ["autocomplete", "variant"],
"enabled": true,
"dangerous": false
},
{
"name": "Transparency",
"icon": "opacity",
"description": "Change shell transparency",
"command": ["autocomplete", "transparency"],
"enabled": false,
"dangerous": false
},
{
"name": "Random",
"icon": "casino",
"description": "Switch to a random wallpaper",
"command": ["caelestia", "wallpaper", "-r"],
"enabled": true,
"dangerous": false
},
{
"name": "Light",
"icon": "light_mode",
"description": "Change the scheme to light mode",
"command": ["setMode", "light"],
"enabled": true,
"dangerous": false
},
{
"name": "Dark",
"icon": "dark_mode",
"description": "Change the scheme to dark mode",
"command": ["setMode", "dark"],
"enabled": true,
"dangerous": false
},
{
"name": "Shutdown",
"icon": "power_settings_new",
"description": "Shutdown the system",
"command": ["systemctl", "poweroff"],
"enabled": true,
"dangerous": true
},
{
"name": "Reboot",
"icon": "cached",
"description": "Reboot the system",
"command": ["systemctl", "reboot"],
"enabled": true,
"dangerous": true
},
{
"name": "Logout",
"icon": "exit_to_app",
"description": "Log out of the current session",
"command": ["loginctl", "terminate-user", ""],
"enabled": true,
"dangerous": true
},
{
"name": "Lock",
"icon": "lock",
"description": "Lock the current session",
"command": ["loginctl", "lock-session"],
"enabled": true,
"dangerous": false
},
{
"name": "Sleep",
"icon": "bedtime",
"description": "Suspend then hibernate",
"command": ["systemctl", "suspend-then-hibernate"],
"enabled": true,
"dangerous": false
},
{
"name": "Settings",
"icon": "settings",
"description": "Configure the shell",
"command": ["caelestia", "shell", "controlCenter", "open"],
"enabled": true,
"dangerous": false
}
],
"dragThreshold": 50,
"vimKeybinds": false,
"enableDangerousActions": false,
"maxShown": 7,
"maxWallpapers": 9,
"specialPrefix": "@",
"useFuzzy": {
"apps": false,
"actions": false,
"schemes": false,
"variants": false,
"wallpapers": false
},
"showOnHover": false,
"favouriteApps": [],
"hiddenApps": []
},
"lock": {
"recolourLogo": false,
"hideNotifs": false
},
"notifs": {
"actionOnClick": false,
"clearThreshold": 0.3,
"defaultExpireTimeout": 5000,
"expandThreshold": 20,
"openExpanded": false,
"expire": false
},
"osd": {
"enabled": true,
"enableBrightness": true,
"enableMicrophone": false,
"hideDelay": 2000
},
"paths": {
"mediaGif": "root:/assets/bongocat.gif",
"sessionGif": "root:/assets/kurukuru.gif",
"noNotifsPic": "root:/assets/dino.png",
"lockNoNotifsPic": "root:/assets/dino.png",
"wallpaperDir": "~/Pictures/Wallpapers",
"lyricsDir": "~/Music/lyrics"
},
"services": {
"audioIncrement": 0.1,
"brightnessIncrement": 0.1,
"maxVolume": 1.0,
"defaultPlayer": "Spotify",
"gpuType": "",
"playerAliases": [{ "from": "com.github.th_ch.youtube_music", "to": "YT Music" }],
"weatherLocation": "",
"useFahrenheit": false,
"useFahrenheitPerformance": false,
"useTwelveHourClock": false,
"smartScheme": true,
"visualiserBars": 45
},
"session": {
"dragThreshold": 30,
"enabled": true,
"vimKeybinds": false,
"icons": {
"logout": "logout",
"shutdown": "power_settings_new",
"hibernate": "downloading",
"reboot": "cached"
},
"commands": {
"logout": ["loginctl", "terminate-user", ""],
"shutdown": ["systemctl", "poweroff"],
"hibernate": ["systemctl", "hibernate"],
"reboot": ["systemctl", "reboot"]
}
},
"sidebar": {
"dragThreshold": 80,
"enabled": true
},
"utilities": {
"enabled": true,
"maxToasts": 4,
"toasts": {
"audioInputChanged": true,
"audioOutputChanged": true,
"capsLockChanged": true,
"chargingChanged": true,
"configLoaded": true,
"dndChanged": true,
"gameModeChanged": true,
"kbLayoutChanged": true,
"kbLimit": true,
"numLockChanged": true,
"vpnChanged": true,
"nowPlaying": false
},
"vpn": {
"enabled": true,
"provider": [
{
"name": "wireguard",
"interface": "your-connection-name",
"displayName": "Wireguard (Your VPN)",
"enabled": false
}
]
},
"quickToggles": [
{
"id": "wifi",
"enabled": true
},
{
"id": "bluetooth",
"enabled": true
},
{
"id": "mic",
"enabled": true
},
{
"enabled": true,
"id": "settings"
},
{
"id": "gameMode",
"enabled": true
},
{
"id": "dnd",
"enabled": true
},
{
"id": "vpn",
"enabled": true
}
]
}
}
EOF3. The “Golden” Launch Command
To prevent the “Type Background unavailable” error, you must explicitly tell Quickshell where the modules are located using the QML2_IMPORT_PATH.
# Kill any broken instances first
killall qs 2>/dev/null
# Set the path and launch
cd ~/.config/quickshell/caelestia
QML2_IMPORT_PATH="$PWD:$PWD/modules:$PWD/services" qs -c .Troubleshooting Common Installation Errors
| Error Message | Fix / Solution |
|---|---|
| “Non-existent attached object” | Switch from quickshell to quickshell-git. |
| “Value is null” on Super key | Ensure the launcher block exists in shell.json. |
| Empty App Drawer | Install fd and run chmod +x scripts/*. |
| Missing Icons/Logo | Update font cache: fc-cache -fv and restart. |
| “startsWith” undefined | Your Hyprland socket isn’t linked. See the Autostart section below. |
4. Permanent Autostart (Hyprland)
To ensure that you don’t have to manualy launch the shell every time you boot, add these lines to your ~/.config/hypr/hyprland.conf:
# Environment Sync
exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP HYPRLAND_INSTANCE_SIGNATURE
# Launch Caelestia
exec-once = QML2_IMPORT_PATH="$HOME/.config/quickshell/caelestia/modules:$HOME/.config/quickshell/caelestia/services" qs -c ~/.config/quickshell/caelestiaBy following these steps, you have successfully completed the process to install Caelestia dot file in Arch Linux. Enjoy your new, high-performance desktop environment!
Have doubts? Ask clearly on the Forum.
Ask Question →
