{"id":3250,"library":"python3-xlib","title":"python3-xlib","description":"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.","status":"active","version":"0.15","language":"python","source_language":"en","source_url":"https://github.com/LiuLang/python3-xlib","tags":["X11","GUI","desktop","Xlib","low-level"],"install":[{"cmd":"pip install python3-xlib","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The Display class is part of the 'display' submodule, not directly under Xlib.","wrong":"import Xlib\ndisplay = Xlib.Display()","symbol":"Display","correct":"import Xlib.display\ndisplay = Xlib.display.Display()"}],"quickstart":{"code":"import Xlib.display\nimport Xlib.error\nimport os\n\ntry:\n    # Attempt to connect to the X server using the DISPLAY environment variable\n    # or a default if not set (e.g., for testing without a real X server).\n    # For actual usage, ensure DISPLAY is correctly set (e.g., ':0' or 'localhost:0').\n    display_name = os.environ.get('DISPLAY', ':0') # Use ':0' as a common default\n    display = Xlib.display.Display(display_name)\n    print(f\"Successfully connected to X display: {display_name}\")\n\n    # Get the root window of the default screen\n    root_window = display.screen().root\n    print(f\"Root window ID: {root_window.id}\")\n\n    # Query the input focus window\n    input_focus = display.get_input_focus()\n    if input_focus.focus:\n        print(f\"Current input focus window ID: {input_focus.focus.id}\")\n    else:\n        print(\"No specific window currently has input focus.\")\n\nexcept Xlib.error.DisplayError as e:\n    print(f\"Error connecting to X display '{display_name}': {e}\")\n    print(\"HINT: Ensure an X server is running and the DISPLAY environment variable is correctly set.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if 'display' in locals() and display:\n        display.close()\n        print(\"Disconnected from X display.\")\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"< 0.10 (pre-python3-xlib)"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.15':46 'allow':20 'bind':10 'consist':55 'current':43 'desktop':59 'direct':41 'draw':35 'enabl':29 'event':40 'graphic':36 'gui':58 'handl':38 'infrequ':53 'input':39 'interact':24 'level':63 'librari':17,49 'low':62 'low-level':61 'maintain':51 'manag':33 'program':22 'protocol':16 'python':9,21 'python3':2,5 'python3-xlib':1,4 'server':28 'system':15 'task':30 'updat':56 'version':44 'window':14,34 'x':13,27 'x11':57 'xlib':3,6,18,60","created_at":"2026-04-11T09:27:27.555051+00:00","updated_at":"2026-04-16T20:31:37.755605+00:00","problems":[{"fix":"Ensure the `DISPLAY` environment variable is correctly set (e.g., `export DISPLAY=:0`), an X server is running and accessible from where the script is executed, or use SSH with X forwarding enabled (`ssh -X user@host`).","cause":"The Python script is unable to establish a connection to the X server, typically due to an incorrect or unset DISPLAY environment variable, no X server running, or network/firewall issues.","error":"Xlib.error.ConnectionError: Can't connect to display"},{"fix":"Verify that the window you are trying to interact with is still valid and exists before making Xlib calls, often by handling potential `BadWindow` exceptions gracefully around operations that might encounter destroyed windows.","cause":"An Xlib request was made using a window ID (XID) that is invalid, refers to a window that has already been destroyed, or does not exist on the X server.","error":"Xlib.error.BadWindow"},{"fix":"Install the library using pip: `pip install python3-xlib` or `pip3 install python3-xlib`.","cause":"The `python3-xlib` library or its underlying `Xlib` module is not installed in the current Python environment or is not found in `sys.path`.","error":"ModuleNotFoundError: No module named 'Xlib'"},{"fix":"Call the `screen` method using parentheses to get the default screen object: `d = display.Display(); s = d.screen()` instead of `d.screen`.","cause":"The `screen` attribute of an `Xlib.display.Display` object is a method that needs to be called to retrieve the default screen object, not accessed as a direct property.","error":"AttributeError: 'Display' object has no attribute 'screen'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.15","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/LiuLang/python3-xlib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/python3-xlib/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}