python3-xlib

0.15 · active · verified Sat Apr 11

python3-xlib is a Python binding for the X Window System protocol library (Xlib). It allows Python programs to interact with the X server, enabling tasks such as managing windows, drawing graphics, and handling input events directly. The current version is 0.15, and the library is maintained with infrequent but consistent updates.

Warnings

breaking This library (`python3-xlib`) is a port for Python 3. It is not compatible with the older `python-xlib` library which was designed for Python 2. Code written for `python-xlib` will likely break.
Fix: Rewrite code to adhere to `python3-xlib`'s API, which is largely similar but has Python 3 specific changes (e.g., byte/string handling). Ensure you install `python3-xlib` not `python-xlib`.
gotcha Connecting to the X server requires an active X server and the `DISPLAY` environment variable to be correctly set. If these conditions are not met, `Xlib.error.DisplayError` will be raised.
Fix: Ensure an X server is running (e.g., a desktop environment, Xephyr, Xvfb). Verify the `DISPLAY` environment variable is set to the correct server address (e.g., `:0`, `localhost:0`). For headless environments, consider using `Xvfb`.
gotcha Many Xlib operations are blocking. For applications requiring responsiveness or concurrent operations, it's crucial to use non-blocking methods where available or run Xlib operations in a separate thread/process.
Fix: Design your application with concurrency in mind. For event processing, consider using `display.next_event(timeout=...)` or handling events in a dedicated thread to avoid blocking your main application loop.
gotcha The `Xlib.display.Display` object holds a connection to the X server. Failing to call `display.close()` can lead to resource leaks on the X server or prevent the connection from being properly terminated.
Fix: Always ensure `display.close()` is called when you are finished with the display connection, preferably within a `finally` block or using a context manager if one becomes available (currently not built-in).

Install

pip install python3-xlib Install with pip

Imports

Display
```
import Xlib.display
display = Xlib.display.Display()
```
The Display class is part of the 'display' submodule, not directly under Xlib.

Quickstart

This quickstart demonstrates how to connect to an X server, retrieve the root window, and query the current input focus. It includes error handling for common connection issues and ensures the display connection is properly closed.

import Xlib.display
import Xlib.error
import os

try:
    # Attempt to connect to the X server using the DISPLAY environment variable
    # or a default if not set (e.g., for testing without a real X server).
    # For actual usage, ensure DISPLAY is correctly set (e.g., ':0' or 'localhost:0').
    display_name = os.environ.get('DISPLAY', ':0') # Use ':0' as a common default
    display = Xlib.display.Display(display_name)
    print(f"Successfully connected to X display: {display_name}")

    # Get the root window of the default screen
    root_window = display.screen().root
    print(f"Root window ID: {root_window.id}")

    # Query the input focus window
    input_focus = display.get_input_focus()
    if input_focus.focus:
        print(f"Current input focus window ID: {input_focus.focus.id}")
    else:
        print("No specific window currently has input focus.")

except Xlib.error.DisplayError as e:
    print(f"Error connecting to X display '{display_name}': {e}")
    print("HINT: Ensure an X server is running and the DISPLAY environment variable is correctly set.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    if 'display' in locals() and display:
        display.close()
        print("Disconnected from X display.")

view raw JSON →