A complete EWMH (Extended Window Manager Hints) implementation in Python 3 and python-xlib. Provides full, Pythonic access to the EWMH spec — query and control any compliant Window Manager, manage window hints, and subscribe to X events.
Tested on: Ubuntu/GNOME · Mint/Cinnamon · Manjaro/KDE · Raspbian/LXDE
⚠️ Wayland note: The new protocol used by GNOME in Ubuntu (Wayland) is not EWMH-compliant. This module is likely not working under Wayland.
- Complete and updated spec coverage — all EWMH properties, atoms, states, window types, hints and messages are implemented and accessible.
- Full read and write support — not just querying, but sending messages and changing properties through the Window Manager.
- Typed, structured API — methods return typed values (integers, strings, named tuples) instead of raw Xlib structs, with
text=Truevariants where atom names are more useful than atom ids. - Multi-display and multi-screen support — convenience functions to enumerate displays, screens and roots, going beyond the default display assumption.
- Window hints management — read and write
WM_HINTSandWM_NORMAL_HINTS, including urgency, icon, input model and size constraints. - Event watching — subscribe to any X event on a window via a background watchdog thread and a callback, without managing the event loop yourself.
- Low-level escape hatch — module-level
getProperty/changeProperty/sendMessagefunctions for custom or non-standard properties, with built-in atom resolution and reply parsing.
from ewmhlib import EwmhRoot, EwmhWindow
# --- Root-level operations ---
root = EwmhRoot()
# Get the active (focused) window
win_id = root.getActiveWindow()
# List all open windows
all_windows = root.getClientList()
# How many virtual desktops are there?
n = root.getNumberOfDesktops()
print(f"{n} desktops available")
# Switch to desktop 1
root.setCurrentDesktop(1)
# --- Window-level operations ---
if win_id:
win = EwmhWindow(win_id)
# Read title and PID
print(win.getName())
print(win.getPid())
# Move the window to desktop 2
win.setDesktop(2)
# Maximize it
win.setMaximized(True, True)
# Focus it
win.setActive()
# Close it
win.setClosed()import time
import Xlib.X
from ewmhlib import EwmhRoot, EwmhWindow
root = EwmhRoot()
win_id = root.getActiveWindow()
if win_id:
win = EwmhWindow(win_id)
def on_event(event):
print("Event received:", event)
win.extensions.checkEvents.start(
[Xlib.X.ConfigureNotify, Xlib.X.ClientMessage],
Xlib.X.StructureNotifyMask | Xlib.X.SubstructureNotifyMask,
on_event
)
print("Move or resize the window. Press Ctrl-C to stop.")
try:
while True:
time.sleep(0.1)
except KeyboardInterrupt:
pass
win.extensions.checkEvents.stop()EWMHlib is used as the Linux backend for PyWinCtl, a cross-platform window control library.
- General functions and variables
- EwmhRoot — Root queries, changes and messages
- EwmhWindow — Window queries, changes and messages
- Properties and Messages functions
- Properties, atoms and hints values
- Data Structs
- Install
- Support / Contributing
- Test
- List of EWMH-compliant window managers
These are module-level — no class instantiation needed.
Provide direct access to the default display, screen and root, ready to use in any Xlib-related function.
| Object | Description |
|---|---|
defaultDisplay |
Default X display connection |
defaultScreen |
Default screen |
defaultRoot |
Default root window |
Useful for multi-display or multi-screen setups. In most single-display scenarios the objects above are sufficient.
| Function | Description |
|---|---|
| getDisplaysInfo() | Get info on all present displays, including screens and roots |
| getDisplayFromRoot() | Get display connection, screen and root from a root id |
| getDisplayFromWindow() | Get display connection, screen and root from a window id |
| getRoots() | Get all root window objects |
Class to access root window features.
For the default root, use the convenience object defaultRootWindow — it gives instant access to all root methods without instantiating anything (equivalent to myRoot = EwmhRoot()).
To instantiate EwmhRoot for a specific root, pass its id. You can obtain it in several ways:
- You already have a root → pass
root.id - You want to search across roots → use
getDisplaysInfo()to enumerate all roots and pick the desired one - You have a window → use
getDisplayFromWindow(window.id)to retrieve the associated root - No argument → retrieves the default display and root
Note: although a regular window and a root window share the same type, EwmhRoot methods are not intended for regular windows.
| Method | Description |
|---|---|
| getSupportedHints() | List hints supported by the Window Manager |
| getClientList() | List managed windows in mapping order (oldest first) |
| getClientListStacking() | List managed windows in stacking order (bottom to top) |
| getNumberOfDesktops() | Get the number of virtual desktops |
| setNumberOfDesktops() | Request a change in the number of virtual desktops |
| getDesktopGeometry() | Get the common size of all desktops |
| setDesktopGeometry() | Request a change in the desktop geometry |
| getDesktopViewport() | Get the top-left corner of each desktop's viewport |
| setDesktopViewport() | Request a change in the current desktop viewport |
| getCurrentDesktop() | Get the index of the current desktop |
| setCurrentDesktop() | Switch to a different virtual desktop |
| getDesktopNames() | Get the names of all virtual desktops |
| getActiveWindow() | Get the id of the currently active (focused) window |
| getWorkArea() | Get the work area geometry for each desktop |
| getSupportingWMCheck() | Check whether a compliant Window Manager is active |
| getVirtualRoots() | Get the list of virtual root window ids |
| setDesktopLayout() | Set the pager's virtual desktop layout |
| getShowingDesktop() | Check whether "show desktop" mode is active |
| setShowingDesktop() | Enter or exit "show desktop" mode |
| setClosed() | Request the Window Manager to close a window |
| setMoveResize() | Move and/or resize a window |
| setWmMoveResize() | Initiate interactive move/resize controlled by the WM |
| setWmStacking() | Restack a window relative to a sibling (pager use) |
| requestFrameExtents() | Ask the WM to estimate frame extents before mapping |
WM_PROTOCOLS messages (PING/SYNC) are available via the wmProtocols subclass (EwmhRoot.wmProtocols.*):
| Method | Description |
|---|---|
| ping() | Send a WM_PING to check if a client is still responsive |
| sync() | Synchronize WM frame repaints with the client window |
These are accessible as EwmhRoot.* and can be passed directly to python-xlib. In most cases they match the default general variables above.
| Variable | Description |
|---|---|
display |
XDisplay connection the root belongs to |
screen |
Screen the root belongs to (Struct) |
root |
Root as an X Window object |
id |
Root window id |
Class to access application window features.
Only a window id is needed to instantiate. You can obtain it in several ways:
- Use an external module:
pywinctl.getAllWindowsWithTitle(title)orpywinctl.getActiveWindow() - Retrieve it from your own application: PyQt's
winId()or Tkinter'sframe()
Note: although a root is also a window, most of these methods will not work with a root.
| Method | Description |
|---|---|
| getName() | Get the window title (_NET_WM_NAME) |
| setName() | Set the window title |
| getVisibleName() | Get the visible name shown by the WM (may differ from getName) |
| setVisibleName() | Set the visible name |
| getIconName() | Get the window icon name |
| setIconName() | Set the window icon name |
| getVisibleIconName() | Get the visible icon name shown by the WM |
| setVisibleIconName() | Set the visible icon name |
| getDesktop() | Get the desktop index this window is on (0xFFFFFFFF = all desktops) |
| setDesktop() | Move the window to a specific desktop |
| getWmWindowType() | Get the functional window type (NORMAL, DIALOG, DOCK, etc.) |
| setWmWindowType() | Change the window type |
| getWmState() | Get the list of current window states |
| changeWmState() | Add, remove or toggle a window state |
| setMaximized() | Set or unset horizontal/vertical maximized states |
| setMinimized() | Iconify (minimize) the window |
| getAllowedActions() | Get the list of user actions currently allowed on this window |
| getStrut() | Get reserved screen-border space (legacy, see getStrutPartial) |
| setStrut() | Set reserved screen-border space |
| getStrutPartial() | Get detailed reserved space at each screen border |
| getIconGeometry() | Get the geometry of the window's taskbar icon |
| getPid() | Get the process id (PID) of the window's owner |
| getHandledIcons() | Check whether the pager is handling icons for this window |
| getUserTime() | Get the timestamp of last user activity in this window |
| getFrameExtents() | Get the WM frame extents (left, right, top, bottom) |
| getOpaqueRegion() | Get the fully-opaque rectangles within the window |
| getBypassCompositor() | Check whether the compositor should be bypassed |
| setActive() | Activate (focus) this window |
| setClosed() | Request the WM to close this window |
| changeStacking() | Change this window's stacking position relative to siblings |
| setMoveResize() | Move and/or resize this window |
| setWmMoveResize() | Initiate interactive move/resize via the WM |
| setWmStacking() | Restack this window (pager use) |
| requestFrameExtents() | Ask WM to estimate frame extents before this window is mapped |
| Variable | Description |
|---|---|
display |
XDisplay connection the window belongs to |
screen |
Screen the window belongs to (Struct) |
root |
Root the window belongs to (X Window object) |
rootWindow |
Root the window belongs to (EwmhRoot object) |
XWindow |
X Window object associated with this window |
id |
Window id |
Low-level, non-EWMH window features — hints, protocols, and event monitoring — available via EwmhWindow.extensions.*.
| Method | Description |
|---|---|
| getWmHints() | Get WM_HINTS (input model, icon, urgency, etc.) |
| setWmHints() | Set or update WM_HINTS |
| getWmNormalHints() | Get WM_NORMAL_HINTS (size constraints, gravity, aspect) |
| setWmNormalHints() | Set or update WM_NORMAL_HINTS |
| getWmProtocols() | Get the WM protocols supported by this window |
| addWmProtocols() | Add supported WM protocols |
| delWmProtocols() | Remove supported WM protocols |
| CheckEvents | Watch for X events and invoke a callback |
CheckEvents runs a background watchdog thread. Control it with:
| Method | Description |
|---|---|
| start() | Start watching for events (can be called again to update args) |
| pause() | Pause the watchdog (resume by calling start() again) |
| stop() | Stop and terminate the watchdog thread |
These module-level functions let you query and control windows or roots directly, without instantiating EwmhRoot or EwmhWindow. They are closer to raw Xlib — more flexible for custom or non-standard use cases, but also more verbose. They simplify handling of atoms, replies and data format conversions.
| Function | Description |
|---|---|
| getProperty() | Retrieve a property from a window or root |
| getPropertyValue() | Extract data from a retrieved property struct |
| changeProperty() | Set or change a property on a window or root |
| sendMessage() | Send a ClientMessage event to a window or root |
All EWMH-defined properties, atoms and hint values are accessible through the Props class (ewmhlib.Props.*). They cover everything recognized by the spec, organized into subclasses by category so they're easy to discover and enumerate.
| Subclass | Description |
|---|---|
| Root | Root window properties (client list, desktops, active window…) |
| DesktopLayout | Desktop layout orientation and corner constants |
| Window | Per-window properties (name, desktop, PID, strut…) |
| WindowType | Window type atoms (NORMAL, DIALOG, DOCK, TOOLBAR…) |
| State | Window state atoms (maximized, minimized, fullscreen…) |
| StateAction | State change actions (ADD, REMOVE, TOGGLE) |
| MoveResize | Move/resize direction and edge constants |
| DataFormat | Property data format constants (8, 16, 32 bit) |
| Mode | Property change mode (REPLACE, APPEND, PREPEND) |
| StackMode | Window stacking modes (Above, Below, TopIf…) |
| HintAction | Hint modification actions (KEEP, REMOVE, or new value) |
Named tuples to help interpret the structured data returned by some methods.
| Struct | Description |
|---|---|
| DisplaysInfo | Display/screen/root info returned by getDisplaysInfo() |
| ScreensInfo | Per-screen info |
| WmHints | WM_HINTS fields returned by getWmHints() |
| WmNormalHints | WM_NORMAL_HINTS fields returned by getWmNormalHints() |
To install this module on your system, you can use pip:
python -m pip install ewmhlib
or using uv:
uv add ewmhlib
Alternatively, you can download the wheel file (.whl) available in the Download page and the dist folder, and run this (don't forget to replace 'x.xx' with proper version number):
python -m pip install EWMHlib-x.xx-py3-none-any.whl
You may want to add --force-reinstall option to be sure you are installing the right dependencies version.
Then, you can use it on your own projects just importing it:
import ewmhlib
In case you have a problem, comments or suggestions, do not hesitate to open issues on the project homepage
If you want to use this code or contribute, you can either:
- Create a fork of the repository, or
- Download the repository, uncompress, and open it on your IDE of choice (e.g. PyCharm)
Be sure you install all dev dependencies by running:
uv sync
or python -m venv .venv python -m pip install -e . --group=dev
To test this module on your own system, cd to "tests" folder and run:
uv run test_ewmhlib.py
A (likely) incomplete list of EWMH-compliant window managers (via Wikipedia, here and here):
| Name | Notes |
|---|---|
| aewm | |
| awesome | |
| Blackbox | (1) |
| bspwm | Partial |
| CTWM | (2) |
| Compiz | |
| echinus | |
| edewm | |
| Enlightenment | |
| evilwm | Partial (3) |
| EXWM | Partial |
| Fluxbox | |
| FVWM | |
| goomwwm | |
| herbstluftwm | |
| i3 | |
| IceWM | |
| interfacewm | |
| JWM | |
| KWin (KDE) | |
| LeftWM | |
| Marco | |
| Matchbox | |
| Metacity (GNOME) | |
| Mutter (GNOME/MeeGo) | |
| Notion | |
| Openbox | |
| PekWM | Partial |
| PlayWM | |
| Qtile | |
| Sawfish | Partial |
| spectrwm | |
| subtle | |
| Window Maker | Partial |
| Wingo | |
| WMFS | |
| wmii | |
| Xfwm (Xfce) | |
| xmonad | (4) |
(1) Through 0.65 / from 0.70
(2) As of 4.0.0
(3) Releases following and including version 1.1.0 follow the EWMH standard
(4) Must activate EWMH (XMonad.Hooks.EwmhDesktops)