wev

Monitor all occurring Wayland events

$ wev

$ wev -f [wl_keyboard]

$ wev -f [wl_keyboard]:[key]

$ wev -F [wl_keyboard]:[key]

$ wev -M [path/to/file]

$ wev -g

wev [OPTIONS...]
wev [-h|--help] [-v|--version] [-d|--display <display>] [--interface <interface>] [--opcode <opcode>] [--event <event>] [--request <request>]

-h, --help
    Displays a help message with available options.

-v, --version
    Shows the program's version information.

-d <display>, --display <display>
    Specifies the Wayland display server to connect to. If not provided, it typically defaults to the WAYLAND_DISPLAY environment variable.

--interface <interface>
    Filters the displayed events to only show those associated with a specific Wayland interface name (e.g., wl_pointer, wl_keyboard).

--opcode <opcode>
    Further filters events to a specific numeric opcode within an interface. Requires the --interface option.

--event <event>
    Filters events to a specific event name within an interface. Requires the --interface option.

--request <request>
    Filters events to a specific request name within an interface. Requires the --interface option.

The wev command-line utility serves as an essential tool for developers and users working within the Wayland display server environment. It operates as a minimalistic Wayland client, establishing a connection to the active Wayland compositor.

Upon connection, wev meticulously captures and prints all events it receives from the compositor to standard output. This output includes a wide array of Wayland protocol messages, such as pointer motion, button presses, keyboard input, surface configuration changes, and more. By presenting these low-level interactions, wev provides invaluable insight into the communication flow between a Wayland client and the compositor.

Its primary use case is debugging: developers can observe the exact sequence of events an application receives, helping to diagnose issues where an application misbehaves or to understand the precise protocol interactions during user input. For those developing Wayland compositors or clients, wev is indispensable for verifying protocol compliance and understanding the Wayland specification in a practical context. It is widely considered the Wayland equivalent of the venerable xev tool in the X11 world, making it a fundamental component of any Wayland development toolkit.

wev requires an active Wayland compositor to function. It will not work on an X11-only session.
The output can be extremely verbose and requires familiarity with the Wayland protocol to interpret effectively. Interpreting its output often requires consulting the Wayland protocol specifications.
It is a diagnostic tool; it does not generate or simulate input, only reports what it receives. It is not designed for general user interaction but rather for deep debugging.

To use wev, simply open a terminal in a Wayland session and run:
wev
Then, interact with your desktop (move the mouse, press keys, click buttons). wev will print the corresponding Wayland events directly to your terminal. Press Ctrl+C to exit.

The output of wev consists of raw Wayland protocol messages. Each line typically indicates an event, the interface it belongs to, its opcode, and the parameters associated with the event. Interpreting this output effectively often requires consulting the Wayland protocol specification or interface XML files (e.g., wayland.xml, xdg-shell.xml) to understand the meaning of specific events and their arguments.

wev emerged as a crucial debugging utility during the development and maturation of the Wayland display server protocol. As Wayland aimed to replace the aging X11 system, developers quickly recognized the need for a tool analogous to xev – a simple client that could report all events received from the display server.

Its development is closely tied to the wayland-utils project, which provides a collection of small, useful Wayland programs for testing and debugging. wev has been an integral part of the Wayland ecosystem almost since its inception, evolving alongside the protocol itself to provide an accessible window into Wayland's event-driven architecture.

xev(1): The X11 equivalent for displaying events from the X server., wayland(7): Provides a general overview and introduction to the Wayland protocol., wayland-info(1): A utility to query and display information about the connected Wayland compositor's capabilities., weston(1): A reference implementation of a Wayland compositor.