# plasma-manager: KDE Plasma configuration as Home Manager modules > plasma-manager is an MIT-licensed collection of Home Manager modules that configure KDE Plasma from Nix, covering themes, panels, shortcuts, window rules, fonts, input devices and a set of KDE applications. The judgement is that its module taxonomy maps unusually well onto how Plasma is actually configured, and that its `overrideConfig` option, which deletes your KDE config files, is the one switch to think about twice. **nix-community/plasma-manager** — Manage KDE Plasma with Home Manager [maintainer=@HeitorAugustoLN] - Repository: https://github.com/nix-community/plasma-manager - Website: https://nix-community.github.io/plasma-manager/ - Stars: 1,248 · Forks: 122 - Language: Nix - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/nix-community-plasma-manager ## A module set, not a rewrite of the KDE configuration plasma-manager provides Home Manager modules which allow you to configure KDE Plasma using Nix. The default branch is `trunk`, the primary language is Nix, and the licence is MIT. The design decision that shapes everything else is that this is a set of Home Manager modules rather than a standalone configuration system. Every option is declared in the same place you declare your other home settings, in a `home.nix` or a flake, and Home Manager's activation mechanism does the writing. The module taxonomy follows how Plasma is actually configured rather than how a configuration tool might abstract it. The list from the documentation covers KDE configuration files via the `files` module, and global themes, colorschemes, icons, cursortheme and wallpaper via the `workspace` module. Then desktop icons, widgets and mouse actions via `desktop`, spectacle shortcuts via `spectacle`, shortcuts via `shortcuts`, hotkeys via `hotkeys`, panels and Extra Widgets via `panels`, keyboards, touchpads and mice via `input`, KRunner via `krunner`, the screen locker via `kscreenlocker`, fonts via `fonts`, window rules via `window-rules`, session via `session`, and KDE apps via `apps`. The `apps` module is worth a second look, because it covers specific applications rather than the desktop as a whole. Four KDE apps have modules in the project: ghostwriter, kate, konsole and okular. Those are the four you would most want declared rather than hand-configured, and their inclusion suggests the module set was built by working backwards from a real desktop. The documentation notes there is more functionality than the list above, and more to come in the future. ## Plasma 5 and Plasma 6 live on different branches The version support is handled by branch rather than by configuration, and the documentation is clear about the consequences. plasma-manager supports both Plasma 5 and Plasma 6. The `trunk` branch is the most up-to-date branch and is mainly focused on Plasma 6, but may still work on Plasma 5. If you are running Plasma 5, it is recommended to use the `plasma-5` branch, which is designed to have better compatibility with Plasma 5. Two ways of consuming that branch are given, one for flakes and one for nix-channels. For flakes you use `github:nix-community/plasma-manager/plasma-5` as the flake url. For nix-channels you set the channel url to `https://github.com/nix-community/plasma-manager/archive/plasma-5.tar.gz`. The trade-off is stated directly. The Plasma 5 branch, due to the extra work required for maintaining, may lag behind a bit in features, but in general it should be less broken when used with Plasma 5. And if you want the best experience with plasma-manager, it is recommended running Plasma 6. This is a fork-style maintenance arrangement, and it has a cost that the documentation does not spell out. Two branches mean two places for a fix to land, and the Plasma 5 branch will drift further behind over time. The pragmatic reading is that Plasma 5 support is a bridge for existing installations and the project is heading towards Plasma 6 only, but the branches are both present in the repository today, and the Plasma 5 branch is described as less broken rather than as deprecated. The repository root confirms the packaging shape. There is a `flake.nix` with a `flake.lock`, a `default.nix`, a `modules/` directory holding the module definitions, a `lib/` directory, an `examples/` directory, a `docs/` directory, a `script/` directory, a `test/` directory, a `treefmt.toml` for formatting, and an `.envrc` for a nix development shell. ## The known gaps are listed, including the keybinding one The documentation has a section on what is not well supported at the moment, and it is worth reading before you commit to the project, because the limitations are structural rather than incidental. The first is real-time updates of configuration without having to log out and back in. This is a direct consequence of the Home Manager model. Plasma reads its configuration when the session starts, so a declarative change lands on the next login rather than immediately. That is fine for a machine you rebuild, and awkward for a desktop you tweak all day. The second is usage of high-level modules in the configuration generated by `rc2nix`, which connects to the migration tool discussed below. The third is keybindings to some key combinations, with `Ctrl+Alt+T` and `Print` given as examples and two issue links provided. This one has a plausible cause in the way Plasma handles certain reserved combinations, and it is the kind of limitation that only shows up once you have bound the key you actually wanted. The documentation also says there may be more things the maintainers are not aware of, and invites issues and pull requests if you find others. That is a candid framing, and it is also a signal about the project's maturity: the supported surface is broad, and the unsupported surface is enumerated rather than discovered. There is a separate section for what will not be supported at all, for reasons of technical impossibility. Plasma Login configuration is out of bounds, because it requires root privileges and thus is not suited to a home-manager module. That is a clean boundary, and it is the only one the documentation names. ## overrideConfig makes it declarative, and deletes your config files There is one option in this project that changes the relationship between the module and your existing setup, and it deserves careful reading. By default plasma-manager will simply write the specified configurations to various config files and leave all other options alone. Settings not specified in plasma-manager will be left alone, meaning that configurations made outside plasma-manager will still be set. The downside follows directly. This can lead to different settings on different machines even with the same plasma-manager configuration, because a setting you changed by hand on one machine is still there and is not on the other. Enabling `overrideConfig` fixes that by making it so all options not set by plasma-manager will be set to the default on login. In practice this then becomes a declarative setup, much like what you would expect from most home-manager options and modules. The warning that follows is the important part. Enabling this option will delete all the KDE config-files on home-manager activation, and replace them with config-files generated by plasma-manager. Therefore make sure you back up your KDE config files before enabling this option if you don't want to lose them. So the choice is between two philosophies. The default is additive and forgiving, which suits a machine where you are still finding your way and want the GUI to keep working. The override mode is reproducible and matches what Home Manager does elsewhere, and it treats your hand-tuned KDE configuration as disposable. For a fleet of machines or a rebuild-from-scratch workflow, the override mode is the one that gives you the reproducibility the rest of Nix is for. For a single personal desktop, the default is the less dangerous starting point, and you can move to the other once your configuration is complete. ## rc2nix captures what the GUI wrote, imperfectly Migrating an existing KDE setup is the problem the project addresses with `rc2nix`. This tool will read KDE configuration files and translate them to Nix. The translated configuration is written to standard output. That makes it easy to do two things: generate an initial Plasma Manager configuration file, and see what settings are changed by a GUI tool by capturing a file before and after using the tool and then using `diff`. The second use is the more interesting one, and it is a debugging technique rather than a migration one. Because the output is Nix on standard output, you can diff two invocations and see exactly what the Plasma settings application changed. That turns the GUI into a query tool rather than a configuration surface. The project is honest about the quality of the result. The rc2nix module is not perfect and often will give somewhat suboptimal configurations, because it will in some cases prefer using the `files` module when better configurations can be achieved using higher-level modules. The `files` module writes a configuration file verbatim, which is always correct but is not the idiomatic way to express an intent. A hand-written module using `panels` or `shortcuts` is more readable and survives a Plasma upgrade better, and rc2nix cannot always tell the difference. The tool can be run without cloning the repository: ```sh nix run github:nix-community/plasma-manager ``` Its stated value is to quickly get your configuration up and running, or to convert config files generated by the GUI settings app into Nix expressions. Both are real migration problems, and a tool that gets the bulk of the translation right for free is worth having even if part of the output needs editing by hand. ## Where the examples live and what they cover The examples directory is the on-ramp, and the documentation names four starting points for different situations. There is an example home-manager configuration at `examples/homeManager/home.nix`, with instructions in the accompanying README. There is an example flake.nix for usage with home-manager only at `examples/homeManagerFlake/flake.nix`. There is an example flake.nix for usage with the system configuration at `examples/systemFlake/flake.nix`. And there is an example home.nix showing some of the capabilities of plasma-manager at `examples/home.nix`. The distinction between the third and the first is the one to notice. A home-manager configuration manages your user session. A system configuration is for the machine-level NixOS configuration, and the example shows how plasma-manager fits into that shape rather than into a home-manager one. Both are supported, and the choice depends on whether you manage Plasma through a user configuration or as part of a system profile. The documentation also points at a manual section containing all the supported plasma-manager options, hosted at `nix-community.github.io/plasma-manager/options.html`. That page is the reference for the option names, and it is where you would look to confirm that a specific setting has a module rather than needing the `files` module. The project identifies itself as a community project and welcomes all contributions, on the grounds that KDE Plasma and its apps consist of a lot of configuration options, and that finding a missing option and having the skills to implement it is the contribution that is wanted. The homepage is `nix-community.github.io/plasma-manager/`, the maintainer is named in the repository description, and the repository has no GitHub releases, so the trunk branch is the thing to track. The last push was on 2026-10-09 and the repository is not archived, so the modules are being worked on. ## Conclusion plasma-manager fits a Nix user who wants their KDE Plasma desktop declared in the same configuration file as the rest of their home setup, and who is willing to treat KDE's own settings GUI as a thing you use to discover values rather than to change them. It does not fit a user who wants their Plasma settings to survive outside Nix, and it does not fit a Plasma Login Screen configuration, which is out of scope by design because it needs root. Verify first that you are on the branch matching your Plasma major version, since the `trunk` branch targets Plasma 6 and the `plasma-5` branch is the one to use for Plasma 5, that the specific option you need is present in the module list, since the documentation records what is not well supported, and that you have backed up your `~/.config` KDE files before enabling `overrideConfig`, because that option deletes them on activation. ## FAQ ### How do I get started with plasma-manager? The `examples/` directory holds an example home-manager configuration with instructions, an example flake.nix for home-manager only, an example flake.nix for the system configuration, and an example home.nix showing some of the module's capabilities. The manual page at `nix-community.github.io/plasma-manager/options.html` lists all the supported options. ### Which branch of plasma-manager should I use for Plasma 5? The `plasma-5` branch, which is designed for better compatibility with Plasma 5. With flakes use `github:nix-community/plasma-manager/plasma-5` as the flake url, or with nix-channels set the channel url to `https://github.com/nix-community/plasma-manager/archive/plasma-5.tar.gz`. The branch may lag behind on features but is generally less broken with Plasma 5. ### What does overrideConfig do in plasma-manager? By default the module writes only the settings you specify and leaves the rest alone, so hand-made changes survive but can differ between machines. Enabling `overrideConfig` sets every option not set by plasma-manager to its default on login, making the setup fully declarative, and it deletes all the KDE config files on home-manager activation, so back them up first. ### How do I convert my existing KDE configuration to Nix? Use the `rc2nix` tool, which reads KDE configuration files and writes the Nix translation to standard output. It can be run without cloning the repository with `nix run github:nix-community/plasma-manager`. The documentation notes it is not perfect and often prefers the `files` module where a higher-level module would be better. ### What does plasma-manager not support? Real-time configuration updates without logging out and back in, use of high-level modules in configuration generated by `rc2nix`, and some key combinations including `Ctrl+Alt+T` and `Print`. Plasma Login configuration is explicitly out of scope because it requires root privileges and so does not suit a home-manager module. ## Sources - [Issues](https://github.com/nix-community/plasma-manager/issues) - [License: MIT](https://github.com/nix-community/plasma-manager/blob/trunk/LICENSE) - [nix-community/plasma-manager on GitHub](https://github.com/nix-community/plasma-manager) - [Project website](https://nix-community.github.io/plasma-manager/) - [README](https://github.com/nix-community/plasma-manager/blob/trunk/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nix-community-plasma-manager