Registry / devops / wmctrl

wmctrl

JSON →
library0.5pypypi✓ verified 81d ago

The Python `wmctrl` library (version 0.5) provides a wrapper around the `wmctrl` command-line utility, enabling programmatic control of windows within the X Window System. It allows Python scripts to query window information, activate windows, and perform actions like resizing or moving. The library follows a stable release cadence, with updates typically occurring years apart, reflecting its role as an interface to a mature external tool.

pip install wmctrl
INSTALL
IMPORT
SIG · WMCTRL
W
wmctrl
devopspythonv0.5
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Window
from wmctrl import Window
from wmctrl import Window, get_windows, get_active_window
Desktop
from wmctrl import Desktop
getoutput
from wmctrl import getoutput

This quickstart demonstrates how to list active windows and all open windows using the `wmctrl` library's `get_windows()` and `get_active_window()` functions. It also shows how to activate a window and includes an example of directly invoking the `wmctrl` command-line utility via `subprocess` for more granular control like moving and resizing. Ensure the `wmctrl` command-line utility is installed on your system.

import os from wmctrl import get_windows, get_active_window # Ensure wmctrl command-line utility is installed if os.system('which wmctrl > /dev/null') != 0: print("Error: 'wmctrl' command-line utility not found. Please install it.") print("e.g., sudo apt-get install wmctrl (Debian/Ubuntu)") exit(1) print("--- Active Window ---") active_window = get_active_window() if active_window: print(f"ID: {active_window.id}, Name: {active_window.wm_name}, Class: {active_window.wm_class}") else: print("No active window found.") print("\n--- All Windows ---") windows = get_windows() if windows: for w in windows: print(f"ID: {w.id}, Desktop: {w.desktop}, Name: {w.wm_name[:40]}...") else: print("No windows found.") # Example of activating a specific window by its name (if it exists) # Note: This is an example, ensure a window with 'Firefox' in its name is open. firefox_window = next((w for w in windows if 'Firefox' in w.wm_name), None) if firefox_window: print(f"\nActivating Firefox window: {firefox_window.wm_name}") firefox_window.activate() else: print("\nFirefox window not found to activate.") # Example of moving/resizing a window using wmctrl command directly via subprocess # Requires the window ID (e.g., from an active window or a search) import subprocess if active_window: print(f"\nAttempting to move active window {active_window.id} to 100,100 with size 800x600...") # Gravity 0, X=100, Y=100, Width=800, Height=600. -1 means keep current. try: subprocess.run(['wmctrl', '-ir', active_window.id, '-e', '0,100,100,800,600'], check=True) print("Window moved/resized (check your desktop).") except subprocess.CalledProcessError as e: print(f"Failed to move/resize window: {e}")
Debug
Known issues
breakingThe Python `wmctrl` library is a wrapper. It requires the separate `wmctrl` command-line utility to be installed on your system (e.g., `sudo apt-get install wmctrl` on Debian/Ubuntu). Without the underlying utility, the Python library will not function.
fix
Install the `wmctrl` command-line utility appropriate for your Linux distribution before using the Python library.
affects: All
gotchaWhen launching new applications and immediately attempting to manipulate their windows (e.g., move, resize, activate), you may encounter timing issues where `wmctrl` acts before the window is fully initialized or its title is set. This can lead to commands failing or targeting the wrong window.
fix
Implement a delay (e.g., `time.sleep()`) or a polling mechanism to wait for the target window to appear and be ready before attempting to control it. You can poll `get_windows()` until the expected window is found.
affects: All
gotcha`wmctrl` operations might fail with 'Cannot open display.' errors when run from non-interactive environments like cron jobs or as root. This occurs because the `DISPLAY` and `XAUTHORITY` environment variables, necessary for X11 interaction, are not set or are incorrect in these contexts.
fix
Explicitly set `DISPLAY` (e.g., `:0` or `:1`) and `XAUTHORITY` (e.g., `/home/youruser/.Xauthority`) environment variables for the process running `wmctrl`. You may also need to use `xhost +local:` to allow access.
affects: All
gotcha`wmctrl` may not reliably bring windows on top of applications running in fullscreen mode, especially if those applications hide window borders and decorations.
fix
There is no direct fix within `wmctrl` for this limitation, as it's often a behavior dictated by the fullscreen application or window manager. Consider alternative X11 tools like `xdotool` if this is a critical requirement, or ensure the target application is not truly fullscreen if possible.
affects: All
Upgrade
Version history
0.5latest on PyPI · released Sep 16, 2023
Audit
Dependencies
wmctrl (command-line utility)requiredThis Python library is a wrapper around the external `wmctrl` command-line tool, which must be installed on your system.
Agent activity
10 hits · last 30 days
node
8
Resources