{"id":2737,"library":"python-xlib","title":"Python X Library","description":"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.","status":"active","version":"0.33","language":"en","source_language":"en","source_url":"https://github.com/python-xlib/python-xlib","tags":["x11","gui","desktop","x-window-system","linux","unix"],"install":[{"cmd":"pip install python-xlib","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import xlib\ndisplay = xlib.Display()","symbol":"Display","correct":"import Xlib.display\ndisplay = Xlib.display.Display()"}],"quickstart":{"code":"import Xlib.display\n\ntry:\n    # Connect to the default X server\n    # The DISPLAY environment variable typically specifies the X server.\n    # For remote connections, ensure X forwarding is set up or xhost permissions are granted.\n    display = Xlib.display.Display()\n\n    # Get the root window of the default screen\n    root = display.screen().root\n\n    # Print its geometry (x, y, width, height, border_width, depth)\n    geometry = root.get_geometry()\n    print(f\"Root window geometry: {geometry}\")\n\n    # Example: Query the current mouse pointer position\n    pointer_info = root.query_pointer()\n    print(f\"Mouse pointer at: ({pointer_info.root_x}, {pointer_info.root_y})\")\n\nfinally:\n    # Always close the display connection to release resources\n    if 'display' in locals() and display:\n        display.close()\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"The method `add_extension_error` within extension handling was renamed to `extension_add_error`.","severity":"breaking","affected_versions":">= 0.32"},{"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`.","message":"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).","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"< 0.29"},{"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.","message":"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.","severity":"gotcha","affected_versions":"< 0.25 (memory leak), < 0.24 (Python 3 instability)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}