wl-restart - restart your compositor when it crashes

wl-restart is a simple tool that restarts your compositor when it crashes. It also creates and destroys the Wayland socket for the compositor, so that clients that support seamless compositor reconnects (most KDE programs, e.g. konsole) don't die with it when your compositor crashes.

wl-restart is inspired by KDE's kwin_wayland_wrapper and reuses wl-socket.c from its implementation.

Compositor Support

Your compositor must support Wayland socket handover. The socket is passed to the compositor with the options --socket NAME --wayland-fd FD.

Supported Compositors:

• Kwin (but you should probably use kwin_wayland_wrapper instead, which is default in Plasma 6)
• Hyprland (--kde mechanism)
• Sway (via feature-socket-handover branch, --kde mechanism)
• labwc (via feature-socket-handover branch, --env mechanism)

Other compositors do not support Wayland socket handover as of now. If there are any compositors with support for socket handover missing from this list, please open an issue for it on GitHub.

Client and Toolkit Support

The socket handover implemented by wl-restart and compatible compositors allows Wayland clients to survive a crash or restart of the compositor without losing any state. However, this needs explicit support in the client or toolkit used.

Currently, only Qt6 supports surviving a compositor restart. The environment variable QT_WAYLAND_RECONNECT=1 needs to be set in order for Qt apps to stay alive when the compositor crashes.

A more complete list of toolkits and their state supporting this can be found at in the KDE wiki.

Features

• Restarts your compositor when it crashes
• Don't lose your session (for programs that support seamless Wayland reconnect)
• Configurable max number of crashes before giving up
• Sets WL_RESTART_COUNT to the current restart counter on compositor restart.
• Support for two different experimental socket handover mechanisms
  • --kde: --socket and --wayland-fd
  • --env: WAYLAND_SOCKET_NAME and WAYLAND_SOCKET_FD

Usage

usage: wl-restart [[options] --] <compositor args>

compositor restart helper. restarts your compositor when it
crashes and keeps the wayland socket alive.

options:
  -h,   --help           show this help
  -n N, --max-restarts N restart a maximum of N times (default 10)
        --kde            pass socket via cli options --socket and --wayland-fd (default)
        --env            pass socket via env vars WAYLAND_SOCKET_NAME and WAYLAND_SOCKET_FD

For example, run this in your TTY instead of normally starting your compositor:

• $ wl-restart sway
• $ wl-restart -n 20 hyprland

Installation

wl-restart can be installed from the ArchLinux AUR with the package wl-restart-git.

Dependencies

• CMake
• scdoc (for man pages)

Building

• Run cmake -B build
• Run cmake --build build

Files

• src/wl-restart.c: the main program
• src/wl-socket.c: the socket creation library from kwin_wayland_wrapper

License

This project is licensed under the GNU GPL version 3.0 or later (SPDX GPL-3.0-or-later). The full license text can also be found in the LICENSE file.