xmonad-contrib: hundreds of modules around a deliberately minimal window manager
Contributed modules for xmonad
At a glance
- What is it?
- xmonad-contrib is the community-maintained collection of extension modules for the xmonad window manager, holding hundreds of additional tiling algorithms and extensions. It is a single Haskell package built with Cabal, Stack and Nix, released alongside the core, and it publishes no window manager of its own.
- Who is it for?
- xmonad-contrib suits someone who already runs xmonad and has hit the limit of what the core configuration expresses, because the alternative to adding a module is writing one, and the library is mature enough to have been released alongside the core for years.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Haskell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 22, 2026, and from our analysis. They are not legal advice.
Editorial analysis
A minimal core with a huge pile of extras
The relationship between the two repositories is stated plainly at the top of the project notes. xmonad core is minimal, stable, yet extensible. xmonad-contrib is the home to hundreds of additional tiling algorithms and extension modules. The two combined make for a tiling X11 window manager, and the project describes them as, quite literally, libraries for creating your own window manager.
That last phrase is the one to hold on to. xmonad is not a program you configure through a settings file and a preferences panel; it is a Haskell library that your configuration file imports and wires together. The tiling algorithms decide how windows are arranged, and the extension modules add behaviour such as handling gaps, decorations, status information or key bindings. The consequence for anyone evaluating it is that the feature list is not a checklist you tick, it is a set of modules you choose between, and the two hundred and some of them overlap.
Because the core is deliberately small, the burden of the interesting decisions sits here. A tiling algorithm is the part of a window manager that determines what happens when you open a new window, where it goes and whether the existing ones resize, and the number of plausible answers to that question is where a large module collection earns its keep.
One Haskell package, three build systems
The repository is a single Haskell package rather than a directory of loose scripts, and that has practical consequences for how you install and update it. The package definition is xmonad-contrib.cabal, with a Setup.lhs file, and the source modules live under an XMonad directory, which is the module namespace that the configuration file imports from.
Three build systems are supported, and the configuration for all three sits at the top level. There is a stack.yaml and a stack-master.yaml for Stack, a cabal.project and a cabal.haskell-ci file for the Cabal side, and a flake.nix for Nix, accompanied by a NIX.md document that covers the Nix route in more detail. The cabal.haskell-ci file in particular is the piece that makes the matrix of supported compiler and package versions reproducible, which is how a library with a large dependency surface keeps a wide range of environments building.
The version numbers follow Hackage, and the package is published there, so the usual Haskell install path works. The tests live in a tests directory, scripts holds the helper scripts, and there is a CHANGES.md recording what changed between releases, along with a hint configuration file for the linter that the project uses.
CI across Stack, Cabal and Nix
The badges at the top of the project notes show three separate build workflows, one for Stack, one for Cabal and one for Nix. That is a deliberate and slightly unusual choice, and it maps onto how the community actually builds Haskell: a lot of people arrive at xmonad with a Haskell toolchain already set up, and the project supports that toolchain rather than insisting on its own.
The practical effect for a user is that whichever of the three you already use, the package is built and tested the same way the rest of your Haskell projects are. The Nix route is the most self-contained, since a flake pins the compiler and the dependency set, which is what you want if you are reproducing a configuration on a second machine or building it in a container.
It is also worth noticing what the workflow set implies about the project's health. Three build systems means three sets of dependency resolutions to keep working, which is more maintenance for the maintainers than one, and it is a reasonable proxy for a library that is still being maintained rather than archived.
Versioning and the licence that matches the core
The releases are published under a single version line that covers the whole package. The most recent is v0.18.2, published on 2026-03-07, before that v0.18.1 in August 2024 and v0.18.0 in February 2024. The gap between the last two releases is about eighteen months, which is normal for a mature library of this kind: the changes between point releases are fixes and new modules rather than redesigns, and there is no need to release for a change that is only interesting to a small number of users.
The licensing position is simple and worth stating exactly. The repository is under the BSD-3-Clause licence, and the project notes add that code submitted to the repository is licensed under the same licence as xmonad core itself, with the copyright held by the authors. That is the arrangement a community code collection needs: no CLA, no corporate assignment, and the author of a module keeps the copyright on it.
The last push to the repository was on 2026-10-17, which is more recent than the last release, so work is continuing in the tree even when the version number has not moved.
Contributing, and the four ways to help
The project notes list the ways in, and the list is broader than a typical code contribution invitation. Bug reports and feature ideas go to the issue tracker of this repository or of xmonad core, and so do bug fixes, new features and new extensions, with pull requests accepted in either place. Documentation fixes and improvements are accepted across three repositories, this one, xmonad core and the website repository, which tells you the project treats its documentation as part of the code.
Beyond that, there is helping others in the community and financial support through GitHub Sponsors and Open Collective. A library like this survives on a small number of people spending their evenings on it, and the funding route is a normal one for the ecosystem.
For people who want to write code, the project points at a contributing document for the mechanics of bug reports and code contributions, and at the XMonad.Doc.Developing module for a brief overview of the architecture and the code conventions. That second link is the one that matters most for a new module, because xmonad has a particular model of how a window manager is put together, and a module that ignores it will be awkward to use no matter how well it is written.
Where the instructions actually live
There is a deliberate absence here: this repository does not describe how to install anything. The project notes point elsewhere for installation and configuration, with links to the download and install pages, the configuration tutorial, the documentation index and the community page, all on the xmonad site, plus a link to the instructions for installing the latest xmonad snapshot from git.
That makes sense for a package that is one layer of a two-part system. Installing the core window manager, installing its extensions, and then writing the configuration file that ties the two together are three separate tasks, and the tutorial is where they meet. The project also asks you to consult the documentation or ask the community if you run into trouble, and the community channels are named: an IRC channel on libera.chat and a Matrix room.
The upshot for an adopter is that the documentation is organised around the core and the site, not around this repository. If you are evaluating xmonad-contrib specifically, the interesting questions are which modules exist and which of them conflict, and the answer to that is a reading of the module list rather than a document. The single most important practical check is the version pairing, because a module written against one release of the core can behave differently against another, and the two are versioned in step.
Editorial conclusion
xmonad-contrib suits someone who already runs xmonad and has hit the limit of what the core configuration expresses, because the alternative to adding a module is writing one, and the library is mature enough to have been released alongside the core for years. It is the wrong choice if you want a window manager with a settings dialog, since this is a set of Haskell modules that you compose into a configuration rather than a program you install and configure, and it is the wrong choice if you are starting from scratch, because the core repository and the configuration tutorial are the places to begin. Before you add a module, read the architecture and code conventions in the XMonad.Doc.Developing module, because a module that fights the core's model is worse than no module at all, and check the version you are pairing with, since the last release was v0.18.2 on 2026-03-07 while the one before it came more than a year earlier. The licence is BSD-3-Clause, matching xmonad core.
Frequently asked questions
What is xmonad-contrib?
It is the community-maintained set of extension modules for the xmonad window manager, holding hundreds of additional tiling algorithms and extension modules. The xmonad core is minimal and extensible, and the two together are described as libraries for creating your own window manager.
How do I install xmonad-contrib?
The project does not document installation in the repository itself and points to the xmonad site instead, with links for downloading and installing, installing the latest xmonad snapshot from git, the configuration tutorial and the documentation index. The package itself is published on Hackage, so the usual Haskell package tooling applies.
What licence is xmonad-contrib under?
The repository is under the BSD-3-Clause licence, and the project notes state that code submitted to it is licensed under the same licence as xmonad core itself, with the copyright held by the authors.
How is xmonad-contrib built and tested?
As a Cabal package with a cabal.project and a cabal.haskell-ci file, and also with Stack and with Nix through a flake.nix and a NIX.md guide. The project runs separate CI workflows for Stack, Cabal and Nix, with the test suite in the tests directory.
Where can I get help with xmonad-contrib?
The documentation and community pages are on xmonad.org, and the project asks you to consult the documentation or ask the community if you run into trouble. The chat channels named are an IRC channel on libera.chat and a Matrix room, and contributions are accepted through the issue trackers and pull requests of this repository and of xmonad core.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/xmonad-xmonad-contrib)Was this useful?