Dusky: an Arch Linux Hyprland dotfiles setup that installs itself with a conductor script

What Dusky actually is, and who it is built for

Dusky is not a distribution and not a package. It is a home directory of configuration files for an Arch Linux desktop, deployed from a bare git repository, plus a set of shell scripts that install the software those configs expect. The repository layout shows this plainly: .config/, user_scripts/, Pictures/, and a .zshrc at the top level, with a .git_dusky_list file tracking the managed paths.

The target user is narrow and clearly stated. The README puts it under Best for: users who already have a fresh, unconfigured Arch Linux installation with Hyprland, set up either via the archinstall script or through a manual install. If you have not installed Arch yet, the README tells you to use the Arch ISO and pick Btrfs as the filesystem and Hyprland as the window manager. That is the whole audience. Someone on Fedora, Debian or macOS is not a partial fit here; they are outside the design.

The feature set is broad for a dotfiles repository. The topics list archlinux, hyprland, waybar, rofi, swaync, wallpapers, configs and scripts. The README describes a Dusky Control Center, a GUI for settings and features, and a music recognition utility. The author states that Quickshell was deliberately avoided to keep the setup lightweight, with terminal interfaces used instead. That is a design position, not a claim you can check from the repository alone.

How the bare repository and the orchestrator script divide the work

Two mechanisms do all the work, and they are worth separating because they fail differently.

The first is the bare git repository. Instead of cloning into a folder and copying files around, Dusky clones with --bare into $HOME/dusky and then checks out with the work tree pointed at your home directory. Files land exactly where the configs expect them, and git tracks your home directory as if it were the project. The trade-off is that every tracked path in your home is now under version control, which is why the README warns that the checkout immediately prints a few errors. The README attributes those errors to matugen not having generated colors yet and says they go away after a wallpaper cycle.

The second mechanism is the orchestrator script, described in the README as a conductor managing around 80 subscripts. It installs dependencies, themes and services. The README makes two claims about its behavior: it detects installed packages and skips them, and it is safe to re-run. The README also states it uses paru to install a few AUR packages and that compiling from source is part of why the run takes 30 to 60 minutes.

That split matters operationally. The git layer is idempotent by nature. The script layer is only as idempotent as its own checks, and the README's troubleshooting section concedes that a script can fail on a rolling release distribution.

Installing Dusky: clone, checkout, run the orchestra

The README assumes you are already booted into a fresh Arch install with Hyprland and BTRFS. The first command ensures git is present. The README notes you need to be online for this.

sudo pacman -Syu --needed git

Next, clone the repository as a bare repository into $HOME/dusky. The --depth 1 flag keeps it shallow, which the README uses to reduce the download.

git clone --bare --depth 1 https://github.com/dusklinux/dusky.git $HOME/dusky

Then check the files out with the work tree set to your home directory. The README states this will print a few errors at the top and that this is expected behavior.

git --git-dir=$HOME/dusky/ --work-tree=$HOME checkout -f

Finally, run the master script. The README warns that you will be prompted for yes or no answers during setup and that you should not leave it unattended. Expect 30 to 60 minutes.

~/user_scripts/arch_setup_scripts/orchestrator.sh

One prerequisite the README raises before any of this: the setup is strictly optimized for BTRFS, for ZSTD compression, copy-on-write and snapshots. It says ext4 should also work but is not recommended. Hardware detection for Intel, Nvidia and AMD is automatic, with a documented fallback of editing ~/.config/uwsm/env and ~/.config/uwsm/env-hyprland to set GPU variables yourself.

When the orchestrator fails, and why that is the expected case

The README's troubleshooting section is unusually honest, and it is the most useful part of the document. It opens with the possibility that a script fails, which it attributes to the rolling release nature of Arch. That is not a bug report; it is a statement about the environment Dusky lives in.

The recovery path is manual and assumes competence. You identify which subscript failed, and the README points to $HOME/user_scripts/setup_scripts/scripts/ as the location. You then run that subscript individually. The README's modularity claim is what makes this possible: a failure in one subscript does not necessarily take down the rest, and the README says the rest of the system usually installs fine.

The README also suggests pasting the script content and the error message into ChatGPT or Gemini to identify the problem, giving a missing dependency or a changed package name as examples. That is a real suggestion from the project, and it tells you something about the maintenance model: package name drift on Arch is expected to be resolved by the user, not by an upstream fix. If you are not comfortable reading shell output and running a single subscript by hand, this setup will stall at the first failure.

A second limitation is the filesystem requirement. BTRFS is described as strict, with ext4 tolerated but not recommended. If your Arch install used ext4, you are outside the optimized path and the README does not describe what breaks.

Keybinds, the cheatsheet, and the learning curve nobody skips

The README names the keybinds as the steepest part of the learning curve. That is a fair self-assessment for any Hyprland configuration, because the window manager's behavior lives almost entirely in keybind definitions and workspace rules that you cannot discover by clicking around.

Dusky's answer is a cheatsheet overlay. Pressing CTRL + SHIFT + SPACE opens a keybinds cheatsheet, and the README notes that commands in that menu can be clicked to run them directly. That is a reasonable mitigation: instead of memorizing the map, you read it once and execute from it. It is also a signal about the intended workflow, which is keyboard-first with a graphical lookup when memory fails.

The README says the keybinds are designed to be intuitive and that you can change them in the config. That is the standard escape hatch, and it is the right one. What the README does not provide is a mapping between Dusky's bindings and Hyprland's defaults, so anyone arriving from a stock Hyprland config should expect to relearn muscle memory rather than extend it.

On Waybar, the README pre-empts a recurring question directly: yes, you can have a horizontal Waybar, and setup asks which side you want it on, bottom, top, left or right. Horizontal and vertical layouts are chosen during setup and the README says they are toggleable from rofi afterward.

How Dusky differs from assembling Hyprland dotfiles yourself

The obvious alternative is picking individual Hyprland dotfiles repositories and wiring them together: one for Waybar, one for Rofi, one for notifications, and a package list you maintain. That approach gives you a smaller blast radius. If the Waybar config breaks, you replace the Waybar config. Nothing else moves.

Dusky inverts that. The README describes a single orchestrated install that places configs, installs dependencies, sets up themes and starts services in one pass, with around 80 subscripts behind one command. The benefit is that the pieces are known to work together: the theme pipeline, the notification daemon and the bar are configured as one system rather than three that happen to coexist. The cost is that you inherit the whole stack's failure modes at once, and the recovery unit is a subscript inside a 30 to 60 minute run rather than a single config file.

A second difference is the theming pipeline. The README credits the MatugenFox project for enabling website theming on Gecko-based browsers such as Firefox, and states the configuration would not have been possible without it. A hand-assembled setup would typically theme the terminal and the bar and stop there. Dusky extends the same color source into browser chrome, which is a meaningfully larger scope and a correspondingly larger dependency on an external project.

If your priority is a desktop you can debug one file at a time, the assembled approach wins. If your priority is a coherent desktop you did not have to design, Dusky's single-command install is the argument.

Maintenance, licensing, and what a re-run costs you

The repository is MIT licensed, which is permissive and places few obligations on you beyond retaining the license notice in copies. The README does not discuss licensing implications, and nothing here is legal advice; read the LICENSE file at the repository root if the terms matter to your situation.

The maintenance picture is mixed in a way worth stating plainly. The last push to the default branch was on 2026-09-28, so the repository is not abandoned. There are no retrieved releases, which means there is no versioned artifact to pin to. You are tracking main, and the README's own troubleshooting section is written for the case where that tracking breaks something. The README also notes the official Discord server has been deleted and that a community server exists without the original developer's involvement, so support runs through a community channel rather than an official one.

Upgrade cost is where the design shows its hand. The orchestrator is described as safe to re-run and as skipping already-installed packages, so the intended upgrade path is to run it again. On a rolling release distribution, that re-run is also the moment when renamed packages surface, which is exactly the failure the README tells you to diagnose yourself. Budget for the 30 to 60 minute window and for reading the output rather than walking away. The README is explicit that you should not leave it unattended because of the prompts.

Editorial conclusion

Adopt Dusky if you already run a fresh Arch install with Hyprland and BTRFS and you want a Waybar, Rofi and SwayNC desktop without assembling it yourself. Do not adopt it if you are on ext4, on a non-Arch distribution without testing, or unwilling to read shell output, because the README states the scripts can fail on a rolling release and expects you to identify and rerun the failing subscript by hand. Before you commit, check the two GPU environment files at ~/.config/uwsm/env and ~/.config/uwsm/env-hyprland against your hardware, and confirm your filesystem is BTRFS rather than ext4.

Frequently asked questions

Official sources

1. dusklinux/dusky on GitHub
2. Issues
3. License: MIT
4. README