{"id":7867,"library":"wmctrl","title":"wmctrl","description":"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.","status":"maintenance","version":"0.5","language":"en","source_language":"en","source_url":"https://github.com/antocuni/wmctrl","tags":["window management","X11","desktop automation","wrapper","subprocess"],"install":[{"cmd":"pip install wmctrl","lang":"bash","label":"Install Python package"},{"cmd":"sudo apt-get install wmctrl # For Debian/Ubuntu\nsudo dnf install wmctrl # For Fedora","lang":"bash","label":"Install underlying wmctrl command-line tool"}],"dependencies":[{"reason":"This Python library is a wrapper around the external `wmctrl` command-line tool, which must be installed on your system.","package":"wmctrl (command-line utility)","optional":false}],"imports":[{"note":"Primary classes and functions for interacting with windows.","symbol":"Window","correct":"from wmctrl import Window, get_windows, get_active_window"}],"quickstart":{"code":"import os\nfrom wmctrl import get_windows, get_active_window\n\n# Ensure wmctrl command-line utility is installed\nif os.system('which wmctrl > /dev/null') != 0:\n    print(\"Error: 'wmctrl' command-line utility not found. Please install it.\")\n    print(\"e.g., sudo apt-get install wmctrl (Debian/Ubuntu)\")\n    exit(1)\n\nprint(\"--- Active Window ---\")\nactive_window = get_active_window()\nif active_window:\n    print(f\"ID: {active_window.id}, Name: {active_window.wm_name}, Class: {active_window.wm_class}\")\nelse:\n    print(\"No active window found.\")\n\nprint(\"\\n--- All Windows ---\")\nwindows = get_windows()\nif windows:\n    for w in windows:\n        print(f\"ID: {w.id}, Desktop: {w.desktop}, Name: {w.wm_name[:40]}...\")\nelse:\n    print(\"No windows found.\")\n\n# Example of activating a specific window by its name (if it exists)\n# Note: This is an example, ensure a window with 'Firefox' in its name is open.\nfirefox_window = next((w for w in windows if 'Firefox' in w.wm_name), None)\nif firefox_window:\n    print(f\"\\nActivating Firefox window: {firefox_window.wm_name}\")\n    firefox_window.activate()\nelse:\n    print(\"\\nFirefox window not found to activate.\")\n\n# Example of moving/resizing a window using wmctrl command directly via subprocess\n# Requires the window ID (e.g., from an active window or a search)\nimport subprocess\nif active_window:\n    print(f\"\\nAttempting to move active window {active_window.id} to 100,100 with size 800x600...\")\n    # Gravity 0, X=100, Y=100, Width=800, Height=600. -1 means keep current.\n    try:\n        subprocess.run(['wmctrl', '-ir', active_window.id, '-e', '0,100,100,800,600'], check=True)\n        print(\"Window moved/resized (check your desktop).\")\n    except subprocess.CalledProcessError as e:\n        print(f\"Failed to move/resize window: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Install the `wmctrl` command-line utility appropriate for your Linux distribution before using the Python library.","message":"The 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.","severity":"breaking","affected_versions":"All"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"`wmctrl` may not reliably bring windows on top of applications running in fullscreen mode, especially if those applications hide window borders and decorations.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Set the `DISPLAY` and `XAUTHORITY` environment variables explicitly before running the script. Example: `export DISPLAY=:0 && export XAUTHORITY=/home/youruser/.Xauthority && python your_script.py`. You might also need `xhost local:root` if running as root.","cause":"The script is running in an environment (e.g., cron, SSH session without X forwarding, as root) where the `DISPLAY` and `XAUTHORITY` environment variables are not correctly set, preventing interaction with the X server.","error":"Cannot open display."},{"fix":"First, check `DISPLAY` and `XAUTHORITY` as described above. Second, ensure the `wmctrl` command-line utility is installed. Third, verify the exact `wmctrl` command works from a regular terminal before embedding it in Python.","cause":"This often indicates that the `wmctrl` command-line utility itself failed. Common reasons include 'Cannot open display.' (see above), or `wmctrl` not being installed, or syntax errors in the command string passed to `subprocess`.","error":"subprocess.CalledProcessError: Command 'wmctrl -l' returned non-zero exit status 1."},{"fix":"Introduce a small delay (`time.sleep(X)`) after launching the application, or implement a loop that repeatedly calls `get_windows()` (or `wmctrl -lp`) until the target window is detected before attempting further actions.","cause":"A common race condition where the `wmctrl` command executes before the newly launched application's window is fully created, mapped, and has its properties (like title and ID) available to `wmctrl`.","error":"Window not found or not responding to commands (e.g., move, resize, activate) after launching an application."}]}