dwl - dwm for Wayland

Join us on our Discord server
Or Matrix: #dwl-official:matrix.org
Or on our IRC channel: #dwl on Libera Chat

dwl is a compact, hackable compositor for Wayland based on wlroots. It is intended to fill the same space in the Wayland world that dwm does in X11, primarily in terms of functionality, and secondarily in terms of philosophy. Like dwm, dwl is:

• Easy to understand, hack on, and extend with patches
• One C source file configurable via config.h
• Tied to as few external dependencies as possible

Getting Started:

Latest semi-stable release

This is probably where you want to start. This builds against the wlroots versions currently shipping in major distributions. If your distribution's wlroots version is older, use an earlier dwl release. The wlroots version against which a given dwl release builds is specified with each release on the release page

Development branch main

Active development progresses on the main branch. The main branch is built against the latest release of wlroots. PRs should target this branch unless they depend on functionality that is not in the current release of wlroots.

Preview branch wlroots-next

The wlroots-next branch is built against the git version of wlroots, which is unstable and changes frequently. PRs requiring functionality from the git version of wlroots should target this branch.

Building dwl

dwl has the following dependencies: - fcft (bar font) - libinput - pixman (bar image) - wayland - wlroots (compiled with the libinput backend) - xkbcommon - wayland-protocols (compile-time only) - pkg-config (compile-time only)

dwl has the following additional dependencies if XWayland support is enabled: - libxcb - libxcb-wm - wlroots (compiled with X11 support) - Xwayland (runtime only)

Install these (and their -devel versions if your distro has separate development packages) and run make. If you wish to build against a released version of wlroots (you probably do), use a release or a 0.x branch. If you want to use the unstable development main branch, you need to use the git version of wlroots.

To enable XWayland, you should uncomment its flags in config.mk.

Configuration

All configuration is done by editing config.h and recompiling, in the same manner as dwm. There is no way to separately restart the window manager in Wayland without restarting the entire display server, so any changes will take effect the next time dwl is executed.

As in the dwm community, we encourage users to share patches they have created. Check out the dwl-patches repository!

Running dwl

dwl can be run on any of the backends supported by wlroots. This means you can run it as a separate window inside either an X11 or Wayland session, as well as directly from a VT console. Depending on your distro's setup, you may need to add your user to the video and input groups before you can run dwl on a VT. If you are using elogind or systemd-logind you need to install polkit; otherwise you need to add yourself in the seat group and enable/start the seatd daemon.

When dwl is run with no arguments, it will launch the server and begin handling any shortcuts configured in config.h. dwl draws a small bar at the top of each monitor; everything else is a Wayland client. Do note that the default background color is grey. This can be modified in config.h.

Programs that should start with the session are started from autostartcmd in config.h, which is spawned once after the backend and XWayland are ready. There is no command-line startup command; autostartcmd is the only entry point, and one SHCMD entry can start as many programs as needed.

Wayland requires a valid XDG_RUNTIME_DIR, which is usually set up by a session manager such as elogind or systemd-logind. If your system doesn't do this automatically, you will need to configure it prior to launching dwl, e.g.:

export XDG_RUNTIME_DIR=/tmp/xdg-runtime-$(id -u)
mkdir -p $XDG_RUNTIME_DIR
dwl

Status information

Information about selected layouts, current window title, app-id, and selected/occupied/urgent tags is written to standard output (see the STATUS INFORMATION section in _dwl_(1)). This information can be used to populate an external status bar with a script that parses it.

The built-in bar also shows the contents of $XDG_RUNTIME_DIR/dwl-status; ~/scripts/status.sh writes that file and the compact $XDG_RUNTIME_DIR/tmux-status that tmux reads. tmux starts the script when dwl is not running.

To get a list of external status bars that work with dwl consult our wiki.

(Known) Java nonreparenting WM issue

Certain IDEs don't display correctly unless an environmental variable for Java AWT indicates that the WM is nonreparenting.

For some Java AWT-based IDEs, such as Xilinx Vivado and Microchip MPLAB X, the following environment variable needs to be set before running the IDE or dwl:

export _JAVA_AWT_WM_NONREPARENTING=1

Replacements for X applications

You can find a list of useful resources on our wiki.

Background

dwl is not meant to provide every feature under the sun. Instead, like dwm, it sticks to features which are necessary, simple, and straightforward to implement given the base on which it is built. Implemented default features are:

• Any features provided by dwm/Xlib: simple window borders, tags, keybindings, client rules, mouse move/resize. Providing a built-in status bar is an exception to this goal, to avoid dependencies on font rendering and/or drawing libraries when an external bar could work well.
• Configurable multi-monitor layout support, including position and rotation
• Configurable HiDPI/multi-DPI support
• Idle-inhibit protocol which lets applications such as mpv disable idle monitoring
• Provide information to external status bars via stdout
• Urgency hints via xdg-activate protocol
• Support screen lockers via ext-session-lock-v1 protocol
• Various Wayland protocols
• XWayland support as provided by wlroots (can be enabled in config.mk)
• Layer shell popups (used by Waybar)
• Damage tracking provided by scenegraph API

Given the Wayland architecture, dwl has to implement features from dwm and the xorg-server. Because of this, it is impossible to maintain the original project goal of 2000 SLOC and have a reasonably complete compositor with features comparable to dwm. However, this does not mean that the code will grow indiscriminately. We will try to keep the code as small as possible.

Features under consideration (possibly as patches) are:

• Protocols made trivial by wlroots

Feature non-goals for the main codebase include:

• Client-side decoration (any more than is necessary to tell the clients not to)
• Client-initiated window management, such as move, resize, and close, which can be done through the compositor
• Animations and visual effects

Acknowledgements

dwl began by extending the TinyWL example provided (CC0) by the sway/wlroots developers. This was made possible in many cases by looking at how sway accomplished something, then trying to do the same in as suckless a way as possible.

Many thanks to suckless.org and the dwm developers and community for the inspiration, and to the various contributors to the project, including:

• Devin J. Pohly for creating and nurturing the fledgling project
• Alexander Courtis for the XWayland implementation
• Guido Cella for the layer-shell protocol implementation, patch maintenance, and for helping to keep the project running
• Stivvo for output management and fullscreen support, and patch maintenance

Also, thanks to our current lead developers:

• @thanatos
• @guidocella