Skip to main content
Version: 2.1

Managing Your Installation

Dux Shell

Managing Your Installation

This guide covers how to manage, update, and configure Dux Shell after installation.

Service Management​

DMS can run as a systemd user service or be launched manually. The dms CLI handles both transparently - commands like dms restart work regardless of how DMS was started.

Dux Installer Users

If you installed via the Dux Installer, DMS is configured as a systemd service by default. The installer runs systemctl --user enable --now dms during setup. You don't need to add dms run to your compositor config.

Systemd provides automatic startup, proper session integration, and logging via journalctl.

Enable and start:

systemctl --user enable --now dms

Common operations:

# Check status
systemctl --user status dms

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

# Restart (or just use: dms restart)
systemctl --user restart dms

# Stop
systemctl --user stop dms

# Disable autostart
systemctl --user disable dms
warning

If using systemd, remove any dms run / spawn "dms" "run" lines from your compositor config to avoid running DMS twice.

niri: Per-Session Control​

niri has proper systemd session integration. You can make DMS only start under niri (not Plasma, GNOME, etc.):

systemctl --user add-wants niri.service dms

This ties the dms service to niri's session, so it won't start under other desktop environments.

Other Compositors​

Hyprland, Sway, MangoWC, and Miracle WM don't have systemd session targets. If you use multiple desktop environments and only want DMS on one of them, disable the systemd unit and start DMS from your compositor config instead:

systemctl --user disable dms

Then add dms run to your compositor's autostart (see Manual Launch below).

Manual Launch​

For testing, debugging, or if you prefer compositor-managed startup:

Compositor autostart:

# Hyprland (~/.config/hypr/hyprland.lua)
hl.on("hyprland.start", function()
  hl.exec_cmd("dms run")
end)

# Sway (~/.config/sway/config)
exec dms run

# niri (~/.config/niri/config.kdl)
spawn-at-startup "dms" "run"

Manual control:

# Launch (foreground)
dms run

# Launch (background/daemon)
dms run -d

# Restart
dms restart

# Kill
dms kill

Switching Between Methods​

From manual to systemd:

  1. Remove dms run from your compositor config
  2. Enable the service: systemctl --user enable --now dms
  3. Restart your compositor or log out/in

From systemd to manual:

  1. Disable the service: systemctl --user disable --now dms
  2. Add dms run to your compositor's autostart
  3. Restart your compositor or log out/in

UI Configuration Directory​

The Quickshell UI is embedded in the dms binary and extracted at runtime, so no separate shell installation is required. The config directory resolves in order:

  1. -c <dir> on any dms command
  2. DMS_SHELL_DIR environment variable
  3. The directory a running instance is already using
  4. The embedded UI

Each candidate must contain shell.qml. To run a custom or development copy of the shell:

dms run -c ~/path/to/quickshell
# or
DMS_SHELL_DIR=~/path/to/quickshell dms run
note

Configs at ~/.config/quickshell/dms or in system XDG paths are no longer discovered automatically. Point at them explicitly with -c or DMS_SHELL_DIR.

Config Directory Migration

Starting in v2.0, user configuration directories have moved from ~/.config/DankMaterialShell to ~/.config/dms (and similarly under ~/.local/state/dms, ~/.cache/dms, and ~/.local/share/dms). On first launch, DMS automatically migrates existing configuration and leaves a compatibility symlink behind (~/.config/DankMaterialShell -> dms), ensuring older scripts and companion tools continue to work seamlessly.

Environment Variables​

DMS and its themed applications need certain environment variables set. Where these live depends on your setup.

Dux Installer Users

The Dux Installer creates ~/.config/environment.d/90-dms.conf with the necessary variables. This file is loaded by systemd for all user sessions. If you need to change Qt theming (e.g., switching to qt6ct), edit this file.

You can also run systemctl --user edit dms and add Environment=VAR=Value lines under [Service]. This only affects DMS and apps it launches, whereas 90-dms.conf applies to all user sessions.

Checking Your Environment​

# See what's currently set
env | grep -E "QT_|GTK|XDG"

# Check the installer's environment file (if it exists)
cat ~/.config/environment.d/90-dms.conf

Manual Configuration​

If you didn't use the installer, set environment variables in your compositor config:

niri (~/.config/niri/config.kdl):

environment {
  QT_QPA_PLATFORM "wayland"
  QT_QPA_PLATFORMTHEME "gtk3"
  ELECTRON_OZONE_PLATFORM_HINT "auto"
}

Hyprland (~/.config/hypr/hyprland.lua):

hl.env("QT_QPA_PLATFORM", "wayland")
hl.env("QT_QPA_PLATFORMTHEME", "gtk3")
hl.env("ELECTRON_OZONE_PLATFORM_HINT", "auto")

Or create ~/.config/environment.d/90-dms.conf:

QT_QPA_PLATFORM=wayland
QT_QPA_PLATFORMTHEME=gtk3
ELECTRON_OZONE_PLATFORM_HINT=auto

Changes to environment.d require logging out and back in (or rebooting) to take effect.

You can also run systemctl --user edit dms and add Environment= lines under [Service]:

[Service]
Environment=QT_QPA_PLATFORM=wayland
Environment=QT_QPA_PLATFORMTHEME=gtk3
Environment=ELECTRON_OZONE_PLATFORM_HINT=auto

This only affects DMS and apps it launches, whereas 90-dms.conf applies to all user sessions.

Drop-in Settings Files​

By default, your DMS settings are stored in settings.json. You may opt to split them between multiple files. This can be useful for example, in conjunction with version control to keep your configuration synced between different machines.

  1. Create a config.d/ directory alongside your settings.json file in the ~/.config/DankMaterialShell/ directory.

  2. Restart DMS

    dms restart

  3. Split your settings

    DMS will now automatically source all json files from config.d/. You can proceed moving your settings from settings.json to your desired files.

note

Keep in mind that it is recommend to save a duplicate of the moved settings before removing the original values from their old file.

File order​

Settings from files found in config.d/ take precedence over those defined in settings.json. The drop-in files are sourced in lexicographic order so settings from 00-common.json may be overshadowed by 05-host-specific.json.

When tweaking the settings from the UI, DMS will only overwrite the effective value.

Default values​

By default, DMS omits settings which haven't been modified. If you cannot find a setting in settings.json because it is still set to its default, you can toggle it in the Settings UI to write it to disk.

Updating​

Package Installations​

Arch & Derivatives:

sudo pacman -Syu dms-shell

Fedora & Derivatives:

sudo dnf upgrade dms

Debian & Ubuntu:

sudo apt update && sudo apt upgrade dms
# or dms-git

OpenSUSE:

sudo zypper refresh && sudo zypper update dms

NixOS:

# Update flake inputs, then:
sudo nixos-rebuild switch

After package updates, restart the shell:

dms restart

Manual Installations​

For source builds or non-packaged distro installer setups:

dms update

For manually compiled dependencies (quickshell, niri, etc.), use the interactive TUI:

dms
# Navigate to Update → select packages to rebuild

After Updating​

  1. Restart DMS: dms restart
  2. Check release notes for breaking changes
  3. Review Settings if new options are available
  4. Update plugins if needed

Uninstalling​

Package Installations​

Arch & Derivatives:

sudo pacman -Rns dms-shell

Fedora, Debian, Ubuntu, OpenSUSE:

# Stable
sudo dnf remove dms      # Fedora
sudo apt remove dms      # Debian/Ubuntu
sudo zypper remove dms   # OpenSUSE

# Or git version
sudo dnf remove dms-git
sudo apt remove dms-git
sudo zypper remove dms-git

Manual/Source Installs​

# Stop and disable the service
systemctl --user disable --now dms

# Remove the binary and shell config
rm -rf ~/.config/quickshell/dms
sudo rm /usr/local/bin/dms

Cleanup​

After uninstalling (package or manual), remove leftover user data:

rm -r ~/.config/dms ~/.local/state/dms ~/.cache/dms

Troubleshooting​

DMS won't start:

  • Check logs: journalctl --user -u dms -n 50 (systemd) or run dms run in a terminal
  • Verify quickshell is installed: which qs
  • Kill stuck processes: dms kill

Settings not applying:

  • Backup and remove ~/.config/DankMaterialShell/settings.json and drop-in files under ~/.config/DankMaterialShell/config.d/*.json (if you have any).
  • Restart DMS to regenerate defaults

Environment variables not working:

  • For environment.d changes: log out and back in
  • For compositor config changes: restart the compositor
  • Verify with echo $QT_QPA_PLATFORMTHEME

Multiple instances running:

dms kill
dms restart