equisdots
Menu

Installation

Requirements and the recommended way to install the equisdots desktop, plus first login and troubleshooting.

The recommended way to install equisdots is the dots meta installer. A single setup run installs the system pieces (packages, fonts, login theme, PAM service, external configs) and the user payload (compositor config, shell, palettes, engines) from every repository.

Requirements

  • Arch Linux or a derivative (EndeavourOS, Manjaro, CachyOS, Garuda).
  • Linux 6.x or newer recommended, 4 GB RAM minimum, 8 GB recommended.
  • Hyprland 0.55 or newer (the configuration is Lua), or niri 26.04 or newer for the niri session.
  • git, rsync, jq, Quickshell (qs), xwww-daemon, mpvpaper and the Hack Nerd Font. The default plugin set also uses cliphist and fd.

dots doctor checks all of these and exits with an error code when something is missing; the full wallpaper pack is optional and about 1.37 GB.

One-command install

The installer clones the whole organization itself; no previous clone is needed:

bash <(curl -fsSL https://raw.githubusercontent.com/equisdots/dots/main/dots) setup -y

The -y flag answers the prompts with the recommended defaults and skips the wallpaper pack. After the first run, the dots command is available at ~/.local/bin/dots.

Manual install

Step by step, from a clone of the dots repository:

git clone https://github.com/equisdots/dots.git
cd dots

./dots system      # system stack (sudo): packages, fonts, login, PAM, xwww
./dots install     # clone every repo and place the user payload
./dots doctor      # verify binaries, clones and installed paths

Prefer setup when possible; it runs both phases in the right order:

./dots setup       # payload first when git/rsync exist, then the system stack
./dots setup -y    # non-interactive with defaults

If git or rsync are missing, setup runs the system stack first (it installs them) and then retries the payload. A failing system phase never aborts the payload phase, and the other way around.

What each phase does

dots system runs the hyprland installer:

  • Installs distro packages via an AUR helper (Hyprland, Quickshell, kitty, dunst, grim, slurp, cliphist, rofi, cava, gpu-screen-recorder and more), plus the Hack Nerd Font and themes (adw-gtk3, Papirus, Bibata).
  • Installs the xwww wallpaper daemon from the checksum-verified prebuilt release, with a source build as fallback.
  • Installs the static SDDM theme from equisdots/login.
  • Installs /etc/pam.d/quickshell for the lock screen and the kitty, Neovim and starship configs.
  • Configures NVIDIA when applicable, including kernel parameters.

dots install clones every repository under ~/.local/share/equisdots and places the payload:

  • Hyprland config to ~/.config/hypr, plus rofi, dunst and cava configs.
  • Quickshell shell, the Nyx mascot island, palettes, theme-sync, davinci, timex and xturing.
  • The plugin standard (plugin-api, plugin-sdk, the plugins hub) and the default plugin set: screenshots, timex, RSS reader, clipboard, quicknotes, file search, sysmon and keybinds.
  • Wrapper scripts in ~/.local/bin and the monthly updater timer.

install copies over a live config but treats settings.json carefully: it is seeded only when missing and then always merged as defaults plus your values. For a full purge you must remove ~/.config/hypr yourself.

Standalone Hyprland install

Without the meta installer:

git clone https://github.com/equisdots/hyprland.git
cd hyprland
chmod +x install.sh
./install.sh                 # full install
./install.sh --dotfiles-only # config only, no packages
./install.sh --nvidia-only   # NVIDIA setup only
./install.sh -y              # non-interactive defaults

The standalone installer skips the step that calls dots install when it is driven by dots system (DOTS_SYSTEM_RUN=1), because the meta installer runs the payload right after.

Wallpaper daemon

The installer pins a release of xwww. Override it when needed:

XWWW_VERSION=v0.13.2 ./scripts/install-xwww.sh
FORCE_XWWW=1 ./install.sh   # reinstall an existing binary

The niri session (dotsniri)

The same desktop runs on the niri compositor. The niri stack has its own meta installer, dotsniri, which is separate from dots and uses its own clone root (~/.local/share/equisdots-niri), so a parallel dots install is never modified:

bash <(curl -fsSL https://raw.githubusercontent.com/equisdots/niri-meta/main/bin/dotsniri) install
dotsniri doctor            # check binaries, clones, deploy and config
dotsniri desktop niri      # select niri as the default session

dotsniri deploys the niri compositor config (~/.config/niri), the shell overlays that make the shared Quickshell UI compositor-neutral, the plugin standard/default set, and the display-manager session entry. It reuses the shared root: settings.json, palettes, wallpapers and the shell stay under ~/.config/hypr, so Hyprland and niri run side by side from one configuration. See niri compositor for the full picture.

Install and manage plugins

dots install deploys the default plugins through the registry convention without writing toggles, so existing users keep the features. From the CLI:

dots plugins                  # installed plugins and their state
dots plugins available        # the registry: installed vs available
dots plugins add <id>         # fetch, deploy by convention and enable
dots plugins add <id> --no-enable --force
dots plugins remove <id>
dots plugins enable <id>
dots plugins disable <id>

The Plugins panel (SUPER + SHIFT + M) does the same from the UI: every installed plugin has a master switch, and a Configure shortcut when it ships a settings page. The 63-plugin hub and the standard are documented in Plugins and extensions.

Verify the installation

dots doctor
dots list
dots plugins
command -v dots hyprland qs davinci theme-sync
fc-match "Hack Nerd Font"

dots list should report every repository as clean, and dots doctor should end without missing items. Every ! line names what needs attention.

First login

  1. Reboot, especially if the NVIDIA driver changed.
  2. Pick Hyprland (or Niri) at the display manager (SUPER + Return opens kitty, SUPER + D the launcher).
  3. The first boot initializes the wallpaper daemon, picks a random wallpaper and starts the background services.

Troubleshooting

  • git/rsync missing: run ./dots system first, then ./dots install.
  • Clone failed: check the network and rerun ./dots install. Failures are never fatal for the other repositories.
  • System phase failed: the payload is still installed. Inspect ls -t /tmp/hyprland-install-*.log | head -1 and retry ./dots system.
  • Glyphs render as boxes: the Hack Nerd Font is missing; rerun ./dots system.
  • dots or davinci not found: ~/.local/bin is not in PATH (dots doctor flags this).
  • xwww version mismatch: run ./dots update, which reinstalls the pinned release when the running binary differs.
  • A plugin does not appear: check dots plugins, verify its compat with dots doctor, then reload with hyprctl reload (or re-run dotsniri deploy on niri).

Uninstall

./dots uninstall            # removes wrappers and the updater timer
./hyprland/uninstall.sh    # removes deployed configs (standalone installer)

dots uninstall keeps config files and the managed clones; the login theme has its own ./install.sh --uninstall in equisdots/login.

Next steps

Read Updating and diagnosing to keep the installation in sync, then Hyprland desktop or niri compositor for the configuration surface, and Plugins and extensions for the extension layer.

Edit this page on GitHub