# xmonad: a Haskell window manager you configure by writing code

> The xmonad package is the minimal, stable core of an X11 tiling window manager whose configuration file is a compiled Haskell program. It suits engineers who want their window management expressed as code, and it is the wrong tool for anyone who wants a settings dialog.

**xmonad/xmonad** — The core of xmonad, a small but functional ICCCM-compliant tiling window manager

- Repository: https://github.com/xmonad/xmonad
- Website: https://xmonad.org
- Stars: 3,600 · Forks: 299
- Language: Haskell
- License: BSD-3-Clause
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/xmonad-xmonad

## The problem xmonad solves, and who ends up using it

Most window managers expose a fixed set of layouts, key bindings and hooks, and you adapt your habits to them. xmonad takes the opposite position. The README describes the repository as "a minimal, stable, yet extensible core", and the extension surface is the configuration file itself: custom layout algorithms, key bindings and other extensions "may be written by the user in config files". If the arrangement you want does not exist, you write it, in the same language the window manager is written in.

The audience follows from that. This is for engineers who are comfortable reading type signatures and compiler errors, and who treat their desktop as a program they maintain. The second audience is smaller but real: people who do not write Haskell yet but want a window manager whose behaviour is fully inspectable, because every decision lives in source they can read.

It is not for everyone. The README states plainly that windows are arranged automatically to tile the screen without gaps or overlap, and that features are accessible from the keyboard, with a mouse optional. If you want overlapping windows you drag around, or a preferences window with checkboxes, the design is aimed away from you.

## How the core, xmonad-contrib and your config fit together

There are three layers, and the repository only contains the first. The xmonad package is the core, described in the README as minimal and stable. xmonad-contrib is a separate library of "hundreds of additional community-maintained tiling algorithms and extension modules". Your own configuration is the third layer, and it is not a data file: it is a Haskell module that imports the core, imports whatever you need from contrib, and is compiled against them.

That compilation step is the mechanism that matters. Changing a key binding means editing source and rebuilding, which is why a configuration mistake surfaces as a compiler error rather than as a window manager that starts and then misbehaves. The README frames the two libraries together as "quite literally, libraries for creating your own window manager", which is an accurate description of the data flow: your program is the entry point, and the window manager is the runtime it produces.

Layouts are applied dynamically, and the README notes that different layouts may be used on each workspace. Xinerama is supported, so windows can be tiled across several physical screens. Both of those are core behaviours rather than contrib add-ons, which is worth knowing when you decide how much of contrib you actually need.

## Installing xmonad and getting a first session running

The README does not inline installation commands. It points to three pages on xmonad.org: downloading and installing xmonad, installing the latest snapshot from git, and configuring xmonad. Treat those as the authoritative steps, because the right command depends on your distribution and on whether you build from Hackage, from git, or from a packaged snapshot.

What the repository does show is the build tooling. The top level contains xmonad.cabal, stack.yaml, cabal.project and flake.nix, and there are CI workflows for Stack, Cabal and Nix under .github/workflows. So a source build has three supported paths, and the one you pick determines the commands you run. A Stack-based build looks like this:

```bash
stack build
```

Stack reads stack.yaml to resolve the compiler and dependencies, so you should see it select a GHC version and then compile the package. If your distribution packages xmonad instead, the package manager is the shorter route and the xmonad.org download page is where that is documented.

The repository also contains Main.hs at the top level and a TUTORIAL.md. Main.hs is the template your configuration is based on, and the tutorial is the document to read before you edit it. The workflow the tutorial describes is: copy the template to a configuration directory, edit it, rebuild, and restart the window manager. Restarting an X11 window manager from inside a running session is the step people get wrong, so do it once deliberately on a machine you can reboot before you rely on it.

One configuration detail is worth internalising early. Because the config is compiled, a syntax error stops the build rather than the session, and you can keep working in the old window manager while you fix it. The README does not document any rollback mechanism beyond that, so keep your working configuration under version control yourself.

## The X11 boundary is the limitation that decides most adoptions

xmonad is a window manager for X11. That single sentence from the README disqualifies it for anyone running a Wayland session, and the repository offers no Wayland backend. XWayland lets X11 clients run under a Wayland compositor, but the compositor is then the window manager, so xmonad is not in that position. If your distribution has moved its default session to Wayland, this is not a configuration problem you can work around.

The second limitation is the language. Configuration is not a dialect of Haskell or a restricted subset; it is Haskell, compiled with GHC, against the versions of xmonad and xmonad-contrib you have installed. An upgrade that changes a type in contrib can break a configuration that was working. The release history shows the shape of that risk: v0.18.0 arrived in February 2024 and v0.18.1 in March 2026, so the core moves slowly, but contrib is a large community library and its modules are where breakage tends to appear.

The third is the build chain itself. GHC is a large dependency, and the xmonad.cabal file carries version constraints that have to be satisfied by whatever compiler your distribution provides. On a rolling-release distribution that is usually fine. On a long-term-support distribution with an older GHC, expect to install a compiler through Stack or Nix rather than through the system package manager. None of this is hidden, but it is real work, and it is the cost you pay for the extensibility.

## xmonad against i3, dwm and the dynamic tiling managers

The closest comparison is i3, because both are keyboard-driven X11 tiling window managers with workspaces and a manual tiling model. The difference is where configuration lives. i3 reads a text configuration file at startup, so changes take effect on reload and a mistake is reported as a parse error with a line number. xmonad compiles that same information, which means you get the type checker as a reviewer and you can express layouts that no configuration format could describe. You also get a build step between you and every change.

dwm is the other useful reference point. It is also configured by editing source and recompiling, so the workflow is similar, but the language is C and the patches are applied to a copy of the source tree. xmonad's equivalent of a patch is an import from xmonad-contrib, which is a library rather than a set of diffs against a specific revision. That makes composition easier and makes version drift between the core and contrib the thing you watch instead.

bspwm and awesome sit between these poles: bspwm is configured through a socket and external scripts, and awesome is configured in Lua, evaluated at runtime. For a Wayland session, the relevant alternatives are sway and Hyprland, which are compositors rather than window managers and therefore occupy the position xmonad cannot. The honest summary is that xmonad is not the fastest path to a tiled desktop; it is the one that gives you the most control over what the desktop is.

## Maintenance, releases and what the BSD-3-Clause licence means here

The repository is not archived, and the last push was on 2026-06-28. Releases are infrequent by design: v0.18.1 on 2026-03-07, v0.18.0 on 2024-02-03, and v0.17.2 on 2023-04-02. The core package is deliberately small, and the README calls it minimal and stable, so the gap between releases reflects the scope of the package rather than neglect. Your upgrade cost is dominated by xmonad-contrib and by your own configuration, not by the core.

The licence is BSD-3-Clause, which is permissive: it allows use, modification and redistribution, including in closed products, provided the copyright notice and disclaimer are retained. The practical consequence for a desktop configuration is that you can publish your config under any licence you like, and you can vendor the core into an internal build without a copyleft obligation. This is not legal advice, and if you are redistributing xmonad inside a product you should read the LICENSE file in the repository rather than this paragraph.

The maintenance cost that the licence does not cover is the one to budget for: keeping a working GHC and a matching set of package versions. Pin them. The repository ships stack.yaml, cabal.project and flake.nix precisely so that a build is reproducible, and using one of those three is cheaper than tracking whatever the system package manager happens to provide.

## Conclusion

Adopt xmonad if you already read and write Haskell, or are willing to, and you want window management expressed as a compiled program rather than a settings file. Do not adopt it if you need Wayland, if you want a graphical configuration tool, or if a broken recompile during a workday would cost you more than the layout flexibility is worth. Before committing, verify three things: that your display server is X11 rather than Wayland, that the GHC version your distribution ships satisfies the xmonad.cabal constraints, and that you can build and restart the window manager from a terminal before you replace your current session with it.

## FAQ

### What is xmonad?

It is a tiling window manager for X11, written, configured and extensible in Haskell. Windows are arranged automatically without gaps or overlap, and features are reachable from the keyboard. This repository holds the minimal core package; the additional layouts and modules live in xmonad-contrib.

### How do I install xmonad?

The README does not inline the commands. It points to the downloading and installing page on xmonad.org, a separate page for installing the latest snapshot from git, and the configuration tutorial. The repository ships stack.yaml, cabal.project and flake.nix, and CI runs Stack, Cabal and Nix builds.

### How do I use xmonad?

You write a Haskell configuration module that imports the core and whatever you need from xmonad-contrib, then compile it. Layouts are applied dynamically and different layouts may be used on each workspace. The README refers readers to the TUTORIAL.md file and the configuration page for the workflow.

### Is xmonad lightweight?

The core package is described in the README as minimal and stable, and it is a small tiling window manager for X11 rather than a desktop environment. The build chain is the heavier part: configuration is compiled Haskell, so GHC and the package dependencies are involved.

### Is xmonad dead?

The repository is not archived, and the last push was on 2026-06-28. Releases are infrequent: v0.18.1 on 2026-03-07, v0.18.0 on 2024-02-03 and v0.17.2 on 2023-04-02, which matches the README's description of the core as minimal and stable.

## Sources

- [License: BSD-3-Clause](https://github.com/xmonad/xmonad/blob/master/LICENSE)
- [Project website](https://xmonad.org)
- [README](https://github.com/xmonad/xmonad/blob/master/README.md)
- [Releases](https://github.com/xmonad/xmonad/releases)
- [xmonad/xmonad on GitHub](https://github.com/xmonad/xmonad)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xmonad-xmonad