Skip to main content
Version: 2.0

Installation

Dux Modular Shell

Installation

This guide covers installation of Dux Shell across different Linux distributions and methods.

Dependencies​

  • quickshell (required) - The core framework
  • cava (optional) - Audio visualizer widget
  • dcal (optional) - Complete desktop calendar app with native integration for DMS calendar widgets
  • dsearch (optional) - Filesystem search engine
  • matugen (optional) - Material Design color palette generation
  • niri (optional) - DMS Team's choice of Wayland compositor
  • qt6-multimedia (optional) - System sound feedback

For pre-built packages on Fedora, Debian, Ubuntu, and OpenSUSE, see the Dux Repository page.

note

Only Quickshell is required. All other dependencies are optional and enable specific features.

Arch & Derivatives​

dms is available in the official Arch repositories (extra), and as a development package in the AUR.

sudo pacman -S dux-shell

These packages ship the shell, widgets, and CLI. Pair them with niri, hyprland, sway, mangowc, labwc, or miracle-wm packages from the official repositories for a complete desktop stack.

Fedora & Enterprise Linux​

Dux Shell is available through COPR repositories for Fedora 43/44/45, Rawhide, and Enterprise Linux 10 (RHEL, CentOS Stream, Rocky Linux, AlmaLinux) on the latest 10.x minor.

On Enterprise Linux, enable EPEL first (sudo dnf install epel-release, or the EPEL release RPM on RHEL). EL support is in testing and covers niri only.

Existing installs

The COPR repositories moved from avengemedia to duxlabs: duxlabs/dms, duxlabs/dms-git and duxlabs/dux-repo (formerly avengemedia/danklinux). If you installed from the avengemedia COPRs, run dms migrate dux to switch.

sudo dnf install dms

The COPR repositories also provide companion packages such as quickshell-git, dux-calendar, matugen, and other utilities used by the default configuration.

Fedora Atomic & bootc images​

Silverblue, Kinoite, Sericea, Onyx, Bazzite, Bluefin, Aurora, and other rpm-ostree or bootc images don't take dnf install. Packages are layered onto the image with rpm-ostree and become active after a reboot. The Dux Installer detects these hosts and runs in two passes; it never installs packages or asks for a password on an image.

  1. Run duxinstall, pick your compositor and terminal. The Packages To Layer screen prints the exact rpm-ostree commands for your selection.
  2. Run those commands and reboot.
  3. Run duxinstall again. It resumes from the saved choices (~/.local/state/duxinstall/resume.json), re-checks the packages, and deploys the configuration into your home directory.

Headless works the same way: duxinstall -c niri -t ghostty -y prints the layer commands and exits non-zero while packages are missing. Rerun the identical command after the reboot to deploy configs.

To layer the packages yourself instead (niri and ghostty shown):

sudo curl -fsSLo /etc/yum.repos.d/_copr:copr.fedorainfracloud.org:duxlabs:dms.repo \
  https://copr.fedorainfracloud.org/coprs/duxlabs/dms/repo/fedora-$(rpm -E %fedora)/duxlabs-dms-fedora-$(rpm -E %fedora).repo
sudo rpm-ostree install dms niri ghostty quickshell matugen xwayland-satellite
systemctl reboot

Then run dms setup to deploy the configs. Nothing is written outside your home directory.

Update with sudo rpm-ostree upgrade (or dms system update), which upgrades the image and the layered packages together; dms update refuses to run on image-based systems. Uninstall with sudo rpm-ostree uninstall dms.

Zirconium is a ready-made bootc image with Dux Shell preinstalled: sudo bootc switch ghcr.io/zirconium-dev/zirconium:latest.

For the greeter on these images, see Immutable and image-based systems.

Debian & Ubuntu​

Dux Shell is available through Open Build Service (OBS) for Debian and Launchpad PPA for Ubuntu.

Debian​

Packages are published on OBS for Debian 13 (Trixie), Debian Testing, and Debian Sid.

Stable quickshell should come from Debian (see the Dux Debian section). The Dux OBS quickshell package for Debian is deprecated — if you still have it, sudo apt remove quickshell then install the Debian package before continuing.

Existing installs

The OBS repositories moved from home:AvengeMedia to home:duxlabs-dev: home:duxlabs-dev:dms, home:duxlabs-dev:dms-git and home:duxlabs-dev:dux-repo (formerly home:AvengeMedia:danklinux). If you added the home:AvengeMedia repositories, run dms migrate dux to switch.

Select your release, then choose stable or development packages.

# Native quickshell from Debian backports (required before dms)
echo "deb http://deb.debian.org/debian trixie-backports main" | \
  sudo tee /etc/apt/sources.list.d/trixie-backports.list
sudo apt update
sudo apt install -t trixie-backports quickshell

curl -fsSL https://download.opensuse.org/repositories/home:duxlabs-dev:dux-repo/Debian_13/Release.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/home-duxlabs-dev-dux-repo.gpg
echo "deb [signed-by=/etc/apt/keyrings/home-duxlabs-dev-dux-repo.gpg] https://download.opensuse.org/repositories/home:/duxlabs-dev:/dux-repo/Debian_13/ /" | \
  sudo tee /etc/apt/sources.list.d/home-duxlabs-dev-dux-repo.list

curl -fsSL https://download.opensuse.org/repositories/home:/duxlabs-dev:/dms/Debian_13/Release.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/home-duxlabs-dev-dms.gpg
echo "deb [signed-by=/etc/apt/keyrings/home-duxlabs-dev-dms.gpg] https://download.opensuse.org/repositories/home:/duxlabs-dev:/dms/Debian_13/ /" | \
  sudo tee /etc/apt/sources.list.d/home-duxlabs-dev-dms.list

sudo apt update
sudo apt install dms

Ubuntu​

Ubuntu 26.04 LTS+ (Resolute Raccoon) is supported via Launchpad PPA.

Existing installs

The PPAs moved from avengemedia to duxlabs: ppa:duxlabs/dms, ppa:duxlabs/dms-git and ppa:duxlabs/dux-repo (formerly ppa:avengemedia/danklinux). If you added the avengemedia PPAs, run dms migrate dux to switch.

sudo add-apt-repository ppa:duxlabs/dux-repo
sudo add-apt-repository ppa:duxlabs/dms
sudo apt update
sudo apt install dms
tip

Visit the Dux Repository page for OBS and PPA links and more information about available packages.
Add niri or niri-git to your system to get the best experience.

PikaOS​

PikaOS 4+ carries the Dux Labs packages in its own repository, so no extra repository is needed.

sudo apt update
sudo apt install dms

dms-git, dms-greeter, danksearch and dankcalendar are available the same way. quickshell, niri, Hyprland and matugen come from PikaOS's own builds.

OpenSUSE & Derivatives​

Dux Shell is available through the Open Build Service (OBS) for OpenSUSE Tumbleweed, Leap 16/16.1, and Slowroll.

Existing installs

The OBS repositories moved from home:AvengeMedia to home:duxlabs-dev: home:duxlabs-dev:dms, home:duxlabs-dev:dms-git and home:duxlabs-dev:dux-repo (formerly home:AvengeMedia:danklinux). If you added the home:AvengeMedia repositories, run dms migrate dux to switch.

Select your distribution, then choose stable or development packages.

sudo zypper addrepo https://download.opensuse.org/repositories/home:duxlabs-dev:dux-repo/openSUSE_Tumbleweed/home:duxlabs-dev:dux-repo.repo
sudo zypper addrepo https://download.opensuse.org/repositories/home:/duxlabs-dev:/dms/openSUSE_Tumbleweed/home:duxlabs-dev:dms.repo
sudo zypper refresh
sudo zypper install dms

Gentoo (Community)​

Community Maintained

These overlays are maintained by the community, not the DMS team. For issues with the ebuilds, report to the respective overlay repositories.

Dux Shell is available on Gentoo through the GURU overlay.

Enable the official GURU overlay, which packages DMS (dux-desktop/dux-shell) alongside companion tools dux-desktop/dux-gop and dux-desktop/dux-search.

sudo eselect repository enable guru
sudo emaint sync -r guru
note

The guru overlay packages are keyworded ~amd64, so you may need to accept the testing keyword. For example:

echo "dux-desktop/dux-shell ~amd64" | sudo tee -a /etc/portage/package.accept_keywords/dux-shell

Finally emerge the package

sudo emerge --ask dux-desktop/dux-shell

NixOS​

tip

NixOS has dedicated documentation with two installation methods:

Solus​

Dux Shell is available from the official Solus repository. Pair it with niri, hyprland, sway, or labwc packages from the official repositories for a complete desktop stack.

sudo eopkg install dux-shell
tip

Install the niri-session, sway-session, or labwc-session packages for those compositors to appear in the session list for your greeter.

Void Linux​

note

Install DMS from our R2-backed XBPS repositories or build it from source.

Existing installs

The XBPS repositories moved to void.duxlabs.dev, and danklinux/current is now dux-repo/current. If you configured void.danklinux.com, run dms migrate dux to switch.

echo "repository=https://void.duxlabs.dev/dms/current" | sudo tee /etc/xbps.d/dms.conf
echo "repository=https://void.duxlabs.dev/dux-repo/current" | sudo tee /etc/xbps.d/dux.conf
sudo xbps-install -Su
sudo xbps-install -S dms
note

On the first sync, xbps-install will output our signing key fingerprint and ask you to type y to trust and import it. Verify that the key matches our official signing fingerprint.

Only quickshell is strictly required. Install optional features as desired — matugen (theming), cava (audio visualiser), danksearch (search), dankcalendar (calendar), qt6-multimedia (sounds) — and a compositor such as niri, hyprland, or sway. See the Void README for the full optional-dependency list.

Running Wayland from TTY (Without a Display Manager)​

tip

If you use dms-greeter, all seat management, D-Bus initialization, and runtime directories are handled for you automatically. You only need the manual steps below if you choose to bypass display managers entirely and launch your compositor manually from a pure TTY shell.

If you choose to launch your compositor (like niri, Hyprland, or sway) directly from a TTY login prompt instead of using a display manager (like greetd), Void Linux requires some manual runtime configuration because it does not run systemd by default:

1. Configure Seat Management (elogind)​

Wayland compositors require permissions to access input and graphics hardware devices directly. The dms package already depends on dbus and elogind; enable their services:

sudo ln -s /etc/sv/dbus /var/service/
sudo ln -s /etc/sv/elogind /var/service/

Note: Log out of the TTY and log back in (or reboot) so your login gets an elogind session, which grants seat access and sets XDG_RUNTIME_DIR. If you prefer seatd instead, enable it and add your user to the _seatd group, but do not run both seat managers at once.

2. Launch the Session​

A D-Bus session bus is required for desktop utilities (including the DMS daemon and panels) to communicate. Launch your compositor wrapped inside a D-Bus session:

dbus-run-session niri
# or
dbus-run-session Hyprland

3. Handle XDG_RUNTIME_DIR​

Wayland sockets and configurations require XDG_RUNTIME_DIR to be defined. If it is not automatically set on your system (e.g. if you are not running elogind), add the following fallback script to your shell login configuration file (e.g., ~/.bash_profile or ~/.zprofile):

if [ -z "$XDG_RUNTIME_DIR" ]; then
    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    if [ ! -d "$XDG_RUNTIME_DIR" ]; then
        mkdir -p "$XDG_RUNTIME_DIR"
        chmod 700 "$XDG_RUNTIME_DIR"
    fi
fi

All Other Distributions​

warning

This guide doesn't cover compositor installation. You need a compatible Wayland compositor (niri, Hyprland, sway, dwl/MangoWC, Miracle WM, etc.).

1. Install Essential Dependencies​

Quickshell​

If your distribution does not provide a quickshell package, you'll need to build it from source. Quickshell requires:

Base dependencies:

  • cmake, qt6base, qt6declarative, qtshadertools, pkg-config, cli11
  • Private Qt headers for qt6declarative (and qt6wayland on Qt < 6.10)
  • Qt 6.6 or newer. Use Qt 6.10 or newer for the lock screen: on older Qt the lock client exits on an output with a fractional scale whose logical size is not a whole number (for example 2256x1504 at 1.5), and the compositor falls back to its red lockout screen.

Key features and their dependencies:

  • Wayland support (enabled by default) - qt6wayland, wayland, wayland-protocols
  • Crash reporter (recommended) - google-breakpad
  • Jemalloc (recommended for better memory management) - jemalloc
  • System tray - qt6dbus
  • PAM authentication - pam

For complete build instructions and feature flags, see the Quickshell BUILD.md.

AccountsService​

note

AccountsService is needed to persist user profile configurations such as profile pictures. Available in most repositories as accountsservice.

# Arch + Friends
sudo pacman -S accountsservice
# Fedora + Friends
sudo dnf install accountsservice
# Debian, Ubuntu + Friends
sudo apt install accountsservice
# openSUSE + Friends
sudo zypper install accountsservice
# Gentoo
sudo emerge --ask sys-apps/accountsservice

2. Clone the DMS Repository​

Shared widgets live in the dux-qml-common submodule, so clone with --recurse-submodules:

git clone --recurse-submodules https://github.com/duxlabs-dev/dux-shell.git ~/dms

In an existing clone, run git submodule update --init instead — make install fails until the submodule is present.

3. Compile & Install the DMS Backend​

Requires GO 1.26+

cd ~/dms
sudo make install

The Quickshell UI is embedded into the dms binary at build time. The shell runs from the embedded UI unless -c or DMS_SHELL_DIR points elsewhere. The login screen is a separate binary from dux-greeter with its own embedded UI.

note

To uninstall a source build, run sudo make uninstall from the repository directory.

4. Install Optional Integrations​

Install optional components for full functionality using your distribution's package manager:

  • dsearch - Filesystem search engine
  • matugen - Material Design color palette generation
  • i2c-tools - ddc monitor backlight control
  • dcal - Desktop calendar integration
  • cava - Audio visualizer widget
  • qt6-multimedia - System sound feedback

Post Install​

After completing installation:

  1. Generate compositor config (niri, Hyprland, MangoWC): Run dms setup to create a starter configuration with DMS keybinds and autostart. Other compositors (sway, labwc, Miracle WM) are supported but require manual configuration.
  2. Enable the systemd service (recommended) or add dms run to your compositor config
  3. Configure your compositor keybinds - see the Keybinds & IPC guide
  4. Customize appearance via Themes
  5. Extend functionality with Plugins

See Managing Your Installation for detailed guidance on service management, environment variables, and updates.

Dux Installer Users

If you used the Dux Installer or dms setup with systemd, this is already configured. Both bind dms.service to your compositor's session unit.

Enable autostart:

dms systemd enable

This binds dms.service to the running compositor's session unit (niri.service, hyprland-session.target or mango-session.target), so DMS starts only with that compositor. See Systemd service. The sections below show the same wiring by hand.

Manual control:

# Start DMS now
systemctl --user start dms

# Check status
systemctl --user status dms

# View logs
journalctl --user -u dms -f

# Restart DMS
systemctl --user restart dms

# Disable autostart
dms systemd disable
warning

If using systemd autostart, remove dms run / spawn "dms" "run" / exec_once=dms run from your compositor's configuration to avoid running DMS twice.

Compositor-Specific Systemd Setup​

Different compositors have different levels of systemd session integration. Choose the section that matches your compositor.

Why use add-wants?

If you have multiple desktop environments installed (e.g., Plasma, GNOME, niri), using systemctl --user enable dms starts DMS in all of them. Using add-wants binds DMS to a specific compositor's service or session target, so it only runs where you want it. DMS won't launch when you log into Plasma or GNOME.

niri​

niri has native systemd session integration. Bind DMS to niri's service:

systemctl --user add-wants niri.service dms

DMS starts when niri starts and stops when niri exits. It won't run in other sessions.

Hyprland​

Hyprland 0.57 and newer ship and start hyprland-session.target themselves, so you can skip creating the unit below. Keep the dbus-update-activation-environment line in your config and still run the add-wants step at the end of this section.

On 0.55 and 0.56, Hyprland doesn't initialize the systemd user session by default. You need to export the environment to systemd for user services to work. dms setup and duxinstall write this unit for you; to create it by hand:

~/.config/systemd/user/hyprland-session.target
[Unit]
Description=Hyprland Session Target
BindsTo=graphical-session.target
Wants=graphical-session-pre.target
After=graphical-session-pre.target
PropagatesStopTo=graphical-session.target

Add to your Hyprland config (after any env = lines):

~/.config/hypr/hyprland.lua
hl.on("hyprland.start", function()
  hl.exec_cmd("dbus-update-activation-environment --systemd --all")
  hl.exec_cmd("systemctl --user start hyprland-session.target")
end)

Bind DMS to the session target:

systemctl --user add-wants hyprland-session.target dms

MangoWC​

MangoWC is a dynamic tiling compositor based on dwl (wlroots). DMS needs MangoWC 0.18 or newer.

MangoWC ships mango-session.target (since 0.17.1) and starts it itself after exporting the environment to systemd, so you only need the add-wants step at the end of this section. If your package doesn't install the target, create it by hand:

~/.config/systemd/user/mango-session.target
[Unit]
Description=MangoWC Session Target
Requires=graphical-session.target
After=graphical-session.target

Add to your MangoWC config:

~/.config/mango/config.conf
exec_once=dbus-update-activation-environment --systemd --all
exec_once=systemctl --user start mango-session.target

Bind DMS to the session:

systemctl --user add-wants mango-session.target dms

Sway​

Sway (wlroots-based) needs the environment exported for systemd services.

Create a session target:

~/.config/systemd/user/sway-session.target
[Unit]
Description=Sway Session Target
Requires=graphical-session.target
After=graphical-session.target

Add to your Sway config:

~/.config/sway/config
exec dbus-update-activation-environment --systemd --all
exec systemctl --user start sway-session.target

Bind DMS to the session:

systemctl --user add-wants sway-session.target dms

Miracle WM​

Miracle WM is a tiling Wayland compositor built on Mir. Like other compositors without native systemd session integration, it requires manual environment export.

Create a session target:

~/.config/systemd/user/miracle-wm-session.target
[Unit]
Description=Miracle WM Session Target
Requires=graphical-session.target
After=graphical-session.target

Bind DMS to the session:

systemctl --user add-wants miracle-wm-session.target dms