Python X Library

0.33 · active · verified Fri Apr 10

python-xlib is a Python interface to the X11 Protocol, allowing Python programs to interact with the X Window System. It provides low-level access to Xlib functions and protocol extensions for X client programming. The current version is 0.33, and the library is actively maintained with releases addressing bugs and adding support for various X extensions.

Warnings

breaking The method `add_extension_error` within extension handling was renamed to `extension_add_error`.
Fix: If you are implementing custom X extensions or directly interacting with extension error handling, update any calls to `add_extension_error` to use `extension_add_error`.
gotcha Connecting to the X server (`Xlib.display.Display()`) frequently fails due to an unset or incorrect `DISPLAY` environment variable, an inactive X server, or insufficient permissions (especially for remote connections, requiring `xhost` configuration or SSH X forwarding).
Fix: Verify the `DISPLAY` environment variable is set correctly (e.g., `:0` for local, or `localhost:10.0` for forwarded SSH). Confirm that the X server is running. For remote access, use SSH with X forwarding (`ssh -X user@host`) or configure X server access control using `xhost`.
gotcha Versions prior to 0.29 might experience compatibility issues or crashes when running on Python 3.9 or newer, due to the removal of `array.array.tostring()` in Python 3.9.
Fix: To ensure stability and correct operation on Python 3.9 or later versions, upgrade to `python-xlib` version 0.29 or any subsequent release.
gotcha Older versions (pre-0.25) suffered from an increasing memory usage bug during display instantiation. Additionally, versions prior to 0.24 had general instability and connection issues, particularly on Python 3.x.
Fix: For improved memory management and overall stability, especially within Python 3.x environments, it is strongly recommended to use `python-xlib` version 0.25 or newer.

Install

pip install python-xlib Install stable version

Imports

Display
```
import Xlib.display
display = Xlib.display.Display()
```
The primary entry point for connecting to the X server is `Xlib.display.Display()`. Other components like `Xlib.X` or `Xlib.protocol` are typically accessed via the Display object or are for more advanced, lower-level interactions.

Quickstart

Establishes a connection to the default X server, retrieves the root window's geometry, and queries the current mouse pointer position. This basic example demonstrates how to connect to the X server and perform a simple X request. Ensure the `DISPLAY` environment variable is correctly configured and an X server is running.

import Xlib.display

try:
    # Connect to the default X server
    # The DISPLAY environment variable typically specifies the X server.
    # For remote connections, ensure X forwarding is set up or xhost permissions are granted.
    display = Xlib.display.Display()

    # Get the root window of the default screen
    root = display.screen().root

    # Print its geometry (x, y, width, height, border_width, depth)
    geometry = root.get_geometry()
    print(f"Root window geometry: {geometry}")

    # Example: Query the current mouse pointer position
    pointer_info = root.query_pointer()
    print(f"Mouse pointer at: ({pointer_info.root_x}, {pointer_info.root_y})")

finally:
    # Always close the display connection to release resources
    if 'display' in locals() and display:
        display.close()

view raw JSON →