Skip to main content
Version: 1.6

Advanced Configuration

Dux Shell

Advanced Configuration

DankMaterialShell supports several advanced configuration options through environment variables prefixed with DMS_.

Core Configuration​

DMS_SOCKET​

Custom Unix socket path for DMS internal services communication. Used by DMSService, NetworkService, SessionService, and PortalService for IPC.

DMS_SOCKET=/tmp/custom-dms.sock dms run

Display & Rendering​

DMS_DISABLE_MATUGEN​

Disables matugen dynamic theming system for troubleshooting or when using static themes. Set to 1 or true to disable.

DMS_DISABLE_MATUGEN=1 dms run

DMS_ENABLE_GTK_REFRESH​

Enables the GTK live theme refresh after each matugen rebuild (named DMS_ENABLE_GTK4_REFRESH before v1.6). Running GTK4/libadwaita apps only reload ~/.config/gtk-4.0 colors when the system color-scheme changes, so DMS briefly round-trips color-scheme through the opposite value to force it. Some apps that follow the portal color-scheme (notably Chromium/Chrome) can miss the restore signal and get stuck in the wrong mode, so this is disabled by default — without it, GTK4 apps pick up new colors on their next launch. Set to 1 to enable.

DMS_ENABLE_GTK_REFRESH=1 dms run

DMS_DISABLE_CAVA​

Disables the built-in Cava audio visualizer. Set to 1 to disable.

DMS_DISABLE_CAVA=1 dms run

DMS_DISABLE_LAYER​

Disables layer effects on popout widgets for performance or compatibility reasons. Set to true to disable layer rendering.

DMS_DISABLE_LAYER=true dms run

DMS_NO_DDC​

Disables DDC/CI brightness control for external monitors. DMS probes i2c buses to discover DDC-capable displays and rescans them on hotplug and resume; some monitors handle DDC poorly (brightness commands ignored, or wake behavior disturbed by probe traffic). Set to 1 to skip the DDC backend entirely - laptop backlight control is unaffected.

DMS_NO_DDC=1 dms run

Shadow & Elevation Migration Notes (Power Users)​

If you manually edit settings.json, use:

~/.config/DankMaterialShell/settings.json

Important keys and compatibility notes:

  • Global shadow direction (m3ElevationLightDirection) supports: autoBar, top, topLeft, topRight, bottom.
  • Older/manual left or right values now fall back to top.
  • Per-bar override still uses barConfigs[].shadowIntensity (and related color/opacity keys) to activate bar-specific shadows.
  • Per-bar direction override keys:
    • barConfigs[].shadowDirectionMode: inherit | autoBar | manual
    • barConfigs[].shadowDirection: top | topLeft | topRight | bottom
  • Older/manual per-bar shadowDirection: left/right now falls back to top.

Avoiding duplicate or unexpected shadow behavior:

  • barElevationEnabled: false does not disable an active per-bar override by itself.
  • If a bar still shows shadow, set that bar's shadowIntensity to 0.
  • m3ElevationEnabled: false disables global elevation, but an active per-bar override can still render for that bar.

Migration behavior:

  • Legacy bar shadow state is migrated to barElevationEnabled for older configs.
  • If settings.json is read-only, migration/write-back may not persist until the file is writable.

Layer Variables And Fullscreen Toggles​

DMS uses the compositor's layer-shell protocol for fullscreen stacking. By default, bar, dock, launcher, popout, modal, and notification surfaces use their documented top behavior. Use overlay only for surfaces that should appear above fullscreen windows.

The Settings UI provides Use Overlay Layer toggles for DankBar, Dock, and Launcher. These toggles map directly to top when off and overlay when on. Environment variables are stronger overrides: if a matching DMS_*_LAYER variable is set, that value wins over the UI toggle.

Frame mode is separate from fullscreen policy. A visible Frame renders on the top layer by default. In Connected mode the bar and dock are merged into the frame window itself, so they share that layer rather than opening as separate surfaces. A bar or dock with Use Overlay Layer enabled is the exception: it is not merged into the frame and instead renders as a standalone overlay surface stacked above it. Fullscreen windows are still handled by the compositor and by the per-surface layer choices above.

DMS_DANKBAR_LAYER​

Controls Wayland layer for DankBar panel. Valid values: bottom, overlay, background, or top (default). Useful for window stacking issues.

The Settings UI also has per-bar Use Overlay Layer toggles. If this environment variable is set, it takes precedence over the UI toggle for the bar layer.

DMS_DANKBAR_LAYER=overlay dms run

DMS_POPOUT_LAYER​

Controls Wayland layer for DankBar popout widgets. Valid values: bottom, overlay, background, or top (default). Useful for window stacking issues.

When this is unset, bar-launched popouts inherit the triggering bar's effective layer. For example, a bar with Use Overlay Layer enabled opens its popouts on overlay. Setting DMS_POPOUT_LAYER explicitly overrides that inheritance.

DMS_POPOUT_LAYER=overlay dms run

DMS_MODAL_LAYER​

Controls Wayland layer for modal windows like the launcher, settings panel, and other popups. Valid values: bottom, overlay, background, or top (default).

The Launcher settings page also has Use Overlay Layer. If DMS_MODAL_LAYER is set, the environment variable wins for modal and launcher layering. When it is unset, the launcher can still use overlay through its UI toggle or by inheriting an overlay trigger from the Dock launcher button.

DMS_MODAL_LAYER=overlay dms run

DMS_OSD_LAYER​

Controls Wayland layer for on-screen displays (volume, brightness, etc.). Valid values: bottom, overlay (default), background, or top.

DMS_OSD_LAYER=top dms run

DMS_NOTIFICATION_LAYER​

Controls Wayland layer for notification popups. Valid values: bottom, overlay, background, or top (default).

This remains an environment-only layer override for notification popups.

DMS_NOTIFICATION_LAYER=overlay dms run

System Integration​

DMS_DISABLE_POLKIT​

Disable's the native polkit integration, if you prefer to use a different polkit agent.

DMS_DISABLE_POLKIT=1 dms run

DMS_PREFERRED_BATTERY​

Forces specific battery device when multiple batteries detected (e.g., dual-battery laptops). Provide the UPower device name/path. May need to be set if DMS doesn't detect your battery and shows no stats in the UI.

DMS_PREFERRED_BATTERY=/org/freedesktop/UPower/devices/battery_BAT0 dms run

DMS_HIDE_TRAYIDS​

Comma-separated list of system tray icon IDs to hide from the system tray bar.

DMS_HIDE_TRAYIDS=discord,spotify,steam dms run
DMS_DWL_TAG_COUNT=5 dms run

DMS_FORCE_EXTWS​

Forces use of the ext-workspace-v1 protocol even on compositors that ship an alternative implementation. Useful when you prefer the standardized protocol over a compositor-specific one.

DMS_FORCE_EXTWS=1 dms run

Printing Configuration​

DMS_IPP_HOST​

Specifies the hostname or IP address of the IPP/CUPS print server. Defaults to localhost if not set.

DMS_IPP_HOST=printserver.local dms run

DMS_IPP_PORT​

Specifies the port number for the IPP/CUPS print server. Defaults to 631 (standard IPP port) if not set.

DMS_IPP_PORT=631 dms run

DMS_IPP_USERNAME​

Username for authenticating with the IPP/CUPS print server. Leave unset if authentication is not required.

DMS_IPP_USERNAME=printuser dms run

DMS_IPP_PASSWORD​

Password for authenticating with the IPP/CUPS print server. Leave unset if authentication is not required.

DMS_IPP_PASSWORD=secret dms run

Setting Environment Variables​

Systemd / DankInstall Users

If you manage DMS with systemd (including dankinstall users), set environment variables in ~/.config/environment.d/90-dms.conf:

TERMINAL=ghostty
DMS_DISABLE_MATUGEN=1
DMS_DANKBAR_LAYER=overlay
DMS_HIDE_TRAYIDS=discord,spotify

At least the TERMINAL variable should be present, if you want to use the System Updates widget. Log out and back in for changes to take effect.

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

[Service]
Environment=TERMINAL=ghostty
Environment=DMS_DISABLE_MATUGEN=1

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

niri​

Add to your niri config:

environment {
  DMS_DISABLE_MATUGEN "1"
  DMS_DANKBAR_LAYER "overlay"
  DMS_HIDE_TRAYIDS "discord,spotify"
}

Hyprland​

Add to your Hyprland config:

hl.env("DMS_DISABLE_MATUGEN", "1")
hl.env("DMS_DANKBAR_LAYER", "overlay")
hl.env("DMS_HIDE_TRAYIDS", "discord,spotify")

Sway​

Add to your Sway config:

set $DMS_DISABLE_MATUGEN 1
set $DMS_DANKBAR_LAYER overlay
set $DMS_HIDE_TRAYIDS discord,spotify

Manual Launch​

Set variables before launching:

export DMS_DISABLE_MATUGEN=1
export DMS_DANKBAR_LAYER=overlay
dms run

Use Cases​

Disable dynamic theming:

DMS_DISABLE_MATUGEN=1

Useful for performance testing or when using only static themes.

Hide system tray icons:

DMS_HIDE_TRAYIDS=discord,slack,teams

Clean up system tray by hiding unwanted application icons.

Fix bar layering issues:

DMS_DANKBAR_LAYER=overlay

If DankBar appears behind windows or other issues, adjust the Wayland layer.

Dual battery laptops:

DMS_PREFERRED_BATTERY=/org/freedesktop/UPower/devices/battery_BAT0

Force DMS to use a specific battery when multiple are detected.

Performance tuning:

DMS_DISABLE_LAYER=true

Disable layer effects to improve performance on lower-end hardware.

Remote print server:

DMS_IPP_HOST=printserver.local
DMS_IPP_PORT=631
DMS_IPP_USERNAME=printuser
DMS_IPP_PASSWORD=secret

Connect to a remote CUPS/IPP print server with authentication.