# Caelestia dotfiles: installing the Hyprland desktop on Arch Linux

> Caelestia is a set of Hyprland dotfiles for Arch Linux, installed through the separate caelestia-cli and configured through two Lua override files. The Lua migration and the split into three repositories are the two things to understand before you commit.

**caelestia-dots/caelestia** — A fluid, morphing interface to your Linux desktop

- Repository: https://github.com/caelestia-dots/caelestia
- Stars: 4,458 · Forks: 376
- Language: TypeScript
- License: not declared
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/caelestia-dots-caelestia

## What Caelestia is, and which problem it removes

Caelestia is a dotfiles repository for a Hyprland desktop on Arch Linux. It is not a window manager, a compositor, or a shell. It is the user configuration layer: the Hyprland config files, plus configs for btop, fastfetch, firefox, fish, foot, micro, nvim, spicetify, starship, thunar, uwsm, vscode, zed and zen, all listed as top-level directories in the repository. The shell is a separate project, and the CLI is a separate project. The README describes Caelestia as a multifaceted ecosystem comprising the dotfiles, the shell, and the CLI.

The problem it removes is the assembly work. A Hyprland desktop is a stack of small decisions: which terminal, which launcher, which bar, which notification daemon, which keybind layout. Caelestia makes those decisions once and ships the result. If you already have a working rice you are happy with, this repository has little to offer you. If you are starting from a bare Arch install with Hyprland and want a coherent set of defaults, it removes a weekend of reading wiki pages.

The audience is narrow on purpose. The README's installation section is titled "Installation (Arch Linux)" and the manual path uses pacman and the AUR. No other distribution has a documented path in the README.

## The three-repository split and what lives where

The most important structural fact about Caelestia is that the thing you install is not the thing you clone. The README states plainly that this repository is the main repo of the Caelestia dotfiles and contains user configs for various apps. The shell and the CLI live elsewhere, linked from the README as separate repositories.

That split shows up in configuration too. The shell reads ~/.config/caelestia/shell.json. The CLI reads ~/.config/caelestia/cli.json, which the README says adjusts the CLI's theming and handling of special workspaces. The dotfiles repository itself owns ~/.config/caelestia/hypr-vars.lua and ~/.config/caelestia/hypr-user.lua. Four config surfaces, three repositories. When something behaves unexpectedly, the first question is which of the three you are actually looking at.

The repository root also contains manifest.toml, which drives the install. The README's manual installation instructions tell you to go through the manifest and install all packages from the components you want to enable, then copy all the entries from those components. That is the real unit of installation: a component, not the repository.

## Installing Caelestia on Arch Linux with caelestia install

The documented path is the AUR package and then the CLI's install command. The README gives this example, and it is the whole installation:

```sh
paru -S caelestia-cli
caelestia install
```

The first line installs the CLI from the AUR. The second runs its install command, which is what replaced the legacy install.fish script that used to live in this repository. The README notes that if you have an existing installation made with that legacy script, you should update the CLI and run the install command to complete the migration. So the command is also the upgrade path for old installs.

If you would rather not use the AUR, the README documents a manual route. Clone the repository, read manifest.toml, install the packages for the components you want, and copy the entries for those components. The example given is the hyprland component:

```sh
git clone https://github.com/caelestia-dots/caelestia.git
cd caelestia
sudo pacman -S --needed hyprland xdg-desktop-portal-hyprland xdg-desktop-portal-gtk ttf-jetbrains-mono-nerd
mkdir -p $XDG_CONFIG_HOME/hypr
cp -r hypr/. $XDG_CONFIG_HOME/hypr/
```

Note what that block does not include: it does not copy the other components. The manual route means repeating that pattern per component, which is exactly the work the install command exists to avoid.

One thing the README is explicit about: these dots do not contain a login manager. You install one yourself or log in from a TTY. The README recommends greetd with tuigreet but states that any login manager works.

## Configuring through hypr-vars.lua and hypr-user.lua

The configuring section carries a caution that is worth reading twice. You should never modify any files inside ~/.config/hypr/, because doing so causes conflicts during updates to the dots. Personal changes belong in ~/.config/caelestia/hypr-user.lua or hypr-vars.lua, which the installation and update workflows never modify. Write into ~/.config/hypr/ and the README says updates will not be applied and you will reconcile conflicts by hand each time.

The division between the two files is clear. hypr-vars.lua overrides values the dots already manage: default apps, keybinds, mouse cursor, window decorations. The README points at hypr/variables.lua in the repository as the reference for available variables and their defaults. hypr-user.lua is loaded at the end of the Hyprland loading sequence and takes anything the variables do not cover, such as monitor layout, extra keybinds and window rules. The README says to prefer hypr-vars.lua for options the dots already manage.

The example the README gives for hypr-vars.lua:

```lua
return {
  browser          = "zen-browser",
  editor           = "code",
  blurEnabled      = false,
  windowBorderSize = 3,
  kbTerminal       = "SUPER + Return",
}
```

The file returns a table. The keys shown map to default apps, decoration properties and a keybind, and the README notes windowBorderSize defaults to 1. Because it is Lua rather than a key-value config, anything the variables cannot express goes in hypr-user.lua instead, which is a full Hyprland config file loaded last.

## The Lua migration is the sharpest edge in the project

The README's second important note is that the project switched to Lua for the Hyprland config. If you have a custom ~/.config/caelestia/hypr-user.conf or ~/.config/caelestia/hypr-vars.conf, you must convert it to Lua, manually or with one of the converters available online. The README does not name a specific converter and does not document how the conversion handles anything beyond the file rename.

This is the failure mode to plan for. An installation that predates the switch keeps working until it updates, and then the override files it depends on are in a format the config no longer reads. The symptom is not an error message about Lua; it is your customisations quietly not applying. If you have a hypr-user.conf or hypr-vars.conf on disk, convert it before running the update, and check that the converted file still returns a table in the shape the README's example shows.

The other edge is the legacy installer. install.fish has been removed from this repository, so any tutorial or script that calls it is stale. The replacement is the CLI's install command, which means the CLI has to be installed and current before the migration can happen.

## Where Caelestia is the wrong choice

Caelestia is the wrong tool if you want to understand and own every line of your Hyprland config. The design deliberately puts a layer between you and the compositor config: you edit variables and an override file, and the dots regenerate the rest. That is the point, and it is also the constraint. If you want to restructure the Hyprland config itself, you are fighting the update workflow rather than using it.

It is also the wrong choice outside Arch. The README documents an AUR package and pacman commands. The manual path assumes pacman. A distribution that does not use pacman and does not have the AUR cannot follow either documented route, and the README does not offer a third.

Finally, consider the update model. caelestia update performs a full system update and updates the dots. That couples your dotfiles to a system upgrade. On a machine you need stable, that is a reason to look at a plain Hyprland config you maintain yourself, where a config change and a system upgrade are separate decisions.

## How Caelestia differs from a self-managed Hyprland config

The obvious alternative is Hyprland's own configuration, which the README itself links to for the hypr-user.lua case. The difference in approach is where the defaults live. In a self-managed config, every value is in your file and you are the source of truth. In Caelestia, the defaults live in the repository's hypr/variables.lua and your file only overrides the keys you care about. That means a change upstream to a default you never overrode reaches you on update, which is either a feature or a surprise depending on the value.

A second alternative is a dotfiles manager that symlinks your own configuration into place, which leaves you owning the content and the manager handling deployment. Caelestia inverts that: the content is provided, and your contribution is a diff against it. The README's warning about never editing ~/.config/hypr/ is the clearest statement of that inversion. If your instinct on seeing a default you dislike is to open the file and change it, a symlink-based setup will suit you better than this one.

The practical test is whether you would rather review someone else's keybind table or write your own. Caelestia's default keybinds are extensive, covering workspace groups, special workspaces and window groups with multiple bindings per action, and the README says all of them except the shell restart and kill binds can be overridden in hypr-vars.lua.

## Conclusion

Adopt Caelestia if you run Arch Linux on Hyprland and want a curated set of app configs that you extend through ~/.config/caelestia/hypr-vars.lua and hypr-user.lua rather than by editing files under ~/.config/hypr/. Do not adopt it as a portable dotfiles framework: the documented install path is the AUR package caelestia-cli plus caelestia install, NixOS and CachyOS instructions are not documented, and there is no login manager included. Before installing, check manifest.toml to see which components you actually want, and confirm whether your existing configuration is still in the legacy hypr-user.conf or hypr-vars.conf format, because those must be converted to Lua first.

## FAQ

### What is Caelestia Shell and how does it relate to caelestia-dots/caelestia?

They are separate repositories. This repository, caelestia-dots/caelestia, holds the dotfiles and user configs for various apps, while the shell is its own project linked from the README. The README describes Caelestia as an ecosystem comprising the dotfiles, the shell and the CLI, and the shell's behaviour is configured separately through ~/.config/caelestia/shell.json.

### How do I install Caelestia on Arch Linux?

Install the CLI from the AUR and run its install command: paru -S caelestia-cli followed by caelestia install. The README also documents a manual route where you clone this repository, go through manifest.toml, install the packages for the components you want, and copy their entries.

### How do I start Caelestia after installing it?

The README does not document a start command. It notes that these dots do not contain a login manager, so you install one yourself or log in from a TTY, and it recommends greetd with tuigreet. Once logged into a Hyprland session, the Super key opens the launcher.

### How do I use Caelestia dots for my own customisations?

Put changes in ~/.config/caelestia/hypr-vars.lua for values the dots already manage, such as default apps, keybinds and window decorations, and in ~/.config/caelestia/hypr-user.lua for anything else, including monitor layout and window rules. The README warns that editing files inside ~/.config/hypr/ causes conflicts during updates and prevents new updates from being applied.

### How do I install Caelestia on NixOS or CachyOS?

The README does not document either. Installation is described for Arch Linux only, through the caelestia-cli AUR package plus caelestia install, or manually with pacman and manifest.toml. No NixOS or CachyOS instructions appear in the README.

## Sources

- [caelestia-dots/caelestia on GitHub](https://github.com/caelestia-dots/caelestia)
- [Issues](https://github.com/caelestia-dots/caelestia/issues)
- [README](https://github.com/caelestia-dots/caelestia/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/caelestia-dots-caelestia