Skip to main content
Version: 1.4

NixOS Installation (Flake)

██████╗ ███╗   ███╗███████╗
██╔══██╗████╗ ████║██╔════╝
██║  ██║██╔████╔██║███████╗
██║  ██║██║╚██╔╝██║╚════██║
██████╔╝██║ ╚═╝ ██║███████║
╚═════╝ ╚═╝     ╚═╝╚══════╝

DankMaterialShell can be installed on NixOS either system-wide using the NixOS module or per-user using home-manager. This guide covers both flake-based installation methods.

Native nixpkgs Available

DankMaterialShell is now available in nixpkgs unstable! If you're on NixOS unstable (26.05), see Installation - NixOS for the native nixpkgs installation method which doesn't require flakes.

Installation Methods​

Choose one of the following installation methods based on your needs:

  • NixOS Module: System-wide installation, ideal for multi-user systems or when you want DMS available to all users
  • Home-Manager Module: Per-user installation, ideal for single-user setups or when you want user-specific configurations

Installation​

1. Add Flake Inputs​

First, add the required flake inputs to your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    dms = {
      url = "github:AvengeMedia/DankMaterialShell/stable";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}
Using Unstable Version

If you want to use the unstable (-git) version from the master branch, you can use:

dms.url = "github:AvengeMedia/DankMaterialShell";

However, be aware that the documentation here may not be updated for the latest changes. You're advised to check the Nix modules source code in the repository directly, and keep in mind that it may not work properly.

2. Import the NixOS or home-manager Module​

Add the relevant DankMaterialShell module to your configuration imports:

If you're using the NixOS module:

imports = [
  inputs.dms.nixosModules.dank-material-shell
];

Alternatively, if you're using the home-manager module:

imports = [
  inputs.dms.homeModules.dank-material-shell
];

3. Enable DankMaterialShell​

In your configuration, enable DankMaterialShell:

programs.dank-material-shell.enable = true;

That's it! Rebuild your system (or standalone home-manager configuration) and DankMaterialShell will be installed with sensible defaults.

dgop on NixOS Stable

dgop is not available in nixpkgs stable (25.11). If you're using NixOS stable, you'll need to either:

  • Import dgop from the dgop flake and manually set the package, or
  • Use nixpkgs unstable for dgop

To import dgop from the flake, first add it to your flake inputs:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";xd
    
    dms = {
      url = "github:AvengeMedia/DankMaterialShell/stable";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    
    dgop = {
      url = "github:AvengeMedia/dgop";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

Then configure DankMaterialShell to use the dgop package from the flake:

programs.dank-material-shell = {
  enable = true;
  enableSystemMonitoring = true;
  dgop.package = inputs.dgop.packages.${pkgs.system}.default;
};

niri Integration​

If you're using the niri compositor, the home-manager module provides additional integration options including automatic keybindings and startup configuration.

warning

Note that niri-stable package from niri-flake is on version 25.08, while the needed version for DankMaterialShell is the latest 25.11 (available in nixpkgs).

Prerequisites​

If you choose to use niri-flake, ensure you have it in your inputs:

niri = {
  url = "github:sodiboo/niri-flake";
  inputs.nixpkgs.follows = "nixpkgs";
};

Import it in your home-manager configuration:

imports = [
  inputs.niri.homeModules.niri
];
tip

If you're using the niri-flake's NixOS module (inputs.niri.nixosModules.niri), you don't need to import the home-manager module separately as it's already included.

Enable niri Module​

You can import and use the niri-specific DankMaterialShell module:

imports = [
  inputs.dms.homeModules.dank-material-shell
  inputs.dms.homeModules.niri
];

Enable niri integration features:

programs.dank-material-shell = {
  enable = true;
  niri = {
    enableKeybinds = true;   # Sets static preset keybinds
    enableSpawn = true;      # Auto-start DMS with niri, if enabled
  };
};

This will automatically configure preset keybindings for launcher, notifications, settings, and all other DankMaterialShell features.

note

You should not use both systemd.enable and niri.enableSpawn at the same time, as this will make two instances of DankMaterialShell to be spawned at the same time.

Config includes​

DankMaterialShell's niri home-manager module has a "hack" for config includes support under the programs.dank-material-shell.niri.includes option set.

note

It is not recommended to use both niri.includes (which is enabled by default) and niri.enableKeybinds, as the latter one is less flexible and may introduce conflicts.

Also note that this will overwrite your ~/.config/niri/config.kdl, so your niri-flake generated files will be in ~/.config/niri/hm.kdl instead (or whatever else you define in originalFileName).

In most cases, it should work out of the box, but configuration options are available.

Defaults​

programs.dank-material-shell = {
  enable = true;

  niri.includes = {
    enable = true;             # Enable config includes hack. Enabled by default.

    override = true;           # If disabled, DMS settings won't be prioritized over settings defined using niri-flake
    originalFileName = "hm";   # A new name (without extension) for the config file generated by niri-flake.
    filesToInclude = [         # Files under `$XDG_CONFIG_HOME/niri/dms` to be included into the new config
      "alttab"                 # Please note that niri will throw an error if any of these files are missing.
      "binds"
      "colors"
      "layout"
      "outputs"
      "wpblur"
    ];
  };
}

Polkit Agent​

If you want to use DankMaterialShell's built-in polkit agent and use the niri-flake's NixOS module, you'll need to disable niri-flake's default polkit agent to avoid conflicts:

systemd.user.services.niri-flake-polkit.enable = false;

Configuration Options​

info

The configuration options below work for both the NixOS module and the home-manager module. However, note that:

  • NixOS module: Installs packages system-wide and places quickshell configs in /etc/xdg/quickshell/dms
  • Home-manager module: Additionally supports plugins, default settings, and default session configuration

DankMaterialShell provides numerous configuration options to customize your installation. Here are the main options:

Feature Toggles​

programs.dank-material-shell = {
  enable = true;

  systemd = {
    enable = true;             # Systemd service for auto-start
    restartIfChanged = true;   # Auto-restart dms.service when dank-material-shell changes
  };

  # Core features
  enableSystemMonitoring = true;     # System monitoring widgets (dgop)
  enableVPN = true;                  # VPN management widget
  enableDynamicTheming = true;       # Wallpaper-based theming (matugen)
  enableAudioWavelength = true;      # Audio visualizer (cava)
  enableCalendarEvents = true;       # Calendar integration (khal)
  enableClipboardPaste = true;       # Pasting items from the clipboard (wtype)
};

Custom Quickshell Package​

Quickshell from Source

The DankMaterialShell flake already uses Quickshell built from source by default, as many features rely on unreleased Quickshell features. No additional configuration is needed.

If you need to override the Quickshell package:

programs.dank-material-shell = {
  enable = true;
  quickshell.package = pkgs.quickshell; # or your custom package
};

Settings (home-manager only)​

You can configure settings using the home-manager module:

programs.dank-material-shell = {
  enable = true;

  settings = {
    theme = "dark";
    dynamicTheming = true;
    # Add any other settings here
  };

  session = {
    isLightMode = false;
    # Add any other session state settings here
  };

  clipboardSettings = {
    maxHistory = 25;
    maxEntrySize = 5242880;
    autoClearDays = 1;
    clearAtStartup = true;
    disabled = false;
    disableHistory = false;
    disablePersist = true;
  };
};

If you change settings in the GUI while managing settings with home-manager, you will get a popup saying that settings are read-only, with an option to copy the new settings. You can then use json2nix on the copied settings to update your home-manager configuration.

A complete up-to-date list of available settings can be found here and similarly for session settings an up-to-date list can be found here.

Plugins​

Install DankMaterialShell plugins declaratively. There are two methods:

The dms-plugin-registry flake provides all community plugins as packages with daily updates. This is the simplest way to install plugins using Nix.

First, add the plugin registry as a flake input:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    
    dms = {
      url = "github:AvengeMedia/DankMaterialShell/stable";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    
    dms-plugin-registry = {
      url = "github:AvengeMedia/dms-plugin-registry";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

Then import the module and enable plugins:

{
  imports = [
    inputs.dms.homeModules.dank-material-shell
    inputs.dms-plugin-registry.modules.default
  ];

  programs.dank-material-shell = {
    enable = true;

    plugins = {
      # Simply enable plugins by their ID (from the registry)
      dankBatteryAlerts.enable = true;
      dockerManager.enable = true;
      
      # Add plugin-specific settings
      mediaPlayer = {
        enable = true;

        # You can only define settings here if using the home-manager module
        settings = {
          preferredSource = "spotify";
        };
      };
    };
  };
}

The plugin IDs can be found in the plugin store - it's the last part of the install URL. For example, dms://plugin/install/dankBatteryAlerts has the ID dankBatteryAlerts.

Method 2: Manual Installation from Source​

If you don't want to use the registry flake, you can install plugins manually by providing the source:

programs.dank-material-shell = {
  enable = true;

  plugins = {
    DockerManager = {
      src = pkgs.fetchFromGitHub {
        owner = "LuckShiba";
        repo = "DmsDockerManager";
        rev = "v1.2.0";
        sha256 = "sha256-VoJCaygWnKpv0s0pqTOmzZnPM922qPDMHk4EPcgVnaU=";
      };
      settings = {
        someOption = "value";
      };
    };
    AnotherPlugin = {
      enable = true;
      src = pkgs.another-plugin;
    };
  };
};

Plugin Settings Management (home-manager only)​

You can choose whether or not to manage plugin settings with home-manager through the managePluginSettings option.

programs.dank-material-shell = {
  enable = true;
  
  # Auto-enabled when plugins have settings configured
  managePluginSettings = true;
  
  plugins = {
    somePlugin = {
      enable = true;
      settings = {
        # Your plugin settings here
      };
    };
  };
};
  • If there are no plugins with settings defined but managePluginSettings = true, a minimal plugin_settings.json is created that enables the plugins.
  • If there are plugin settings defined, managePluginSettings defaults to true and those settings are placed in plugin_settings.json.
  • If there are plugin settings defined and managePluginSettings is set to false, there will be a warning, but plugin_settings.json won't be created.

Advanced Configuration​

For a complete list of available options, check the module files in the DankMaterialShell repository:

  • NixOS module: distro/nix/nixos.nix
  • Home-manager module: distro/nix/home.nix
  • niri module: distro/nix/niri.nix
  • Common options: distro/nix/options.nix

Rebuilding​

After making configuration changes, rebuild your system:

# For home-manager standalone
home-manager switch

# For NixOS with home-manager as a module
sudo nixos-rebuild switch

Troubleshooting​

DMS doesn't start automatically​

Make sure you have either:

  • systemd.enable = true for systemd-based startup, or
  • niri.enableSpawn = true for niri-managed startup

Missing dependencies​

Each feature has its own dependency set. If a feature isn't working, ensure the corresponding enable option is set to true. For example, system monitoring requires enableSystemMonitoring = true which installs dgop.

Custom keybindings conflict with niri defaults​

If niri.enableKeybinds = true conflicts with your existing niri configuration, you can disable it and manually configure keybindings using the examples in the Keybinds & IPC guide.

Next Steps​