{"id":2737,"library":"python-xlib","title":"Python X Library","description":"Python X Library (python-xlib) provides a pure Python interface to the X Window System protocol, allowing Python applications to interact with X servers. As of version 0.33, it supports Python 3.6+ and actively receives bug fixes and extension updates, typically with several releases per year addressing compatibility and adding new X protocol extensions.","status":"active","version":"0.33","language":"python","source_language":"en","source_url":"https://github.com/python-xlib/python-xlib","tags":["X11","GUI","display","Xorg","desktop automation"],"install":[{"cmd":"pip install python-xlib","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Requires Python 3.6 or newer.","package":"Python","optional":false}],"imports":[{"symbol":"Display","correct":"import Xlib.display\ndisplay = Xlib.display.Display()"},{"symbol":"X","correct":"import Xlib.X"},{"symbol":"protocol","correct":"import Xlib.protocol"}],"quickstart":{"code":"import Xlib.display\nimport Xlib.X\n\ntry:\n    # Connect to the default display\n    # The DISPLAY environment variable must be set, e.g., export DISPLAY=:0\n    display = Xlib.display.Display()\n    \n    # Get the root window of the default screen\n    root = display.screen().root\n    \n    print(f\"Successfully connected to display: {display.get_display_name()}\")\n    print(f\"Root window ID: {root.id}\")\n    \n    # Example: Create a simple black window\n    # If this causes issues in headless environments, comment out or wrap in try/except\n    try:\n        window = root.create_window(\n            0, 0, 200, 100, 1,                   # x, y, width, height, border_width\n            Xlib.X.CopyFromParent,                # depth\n            Xlib.X.InputOutput,                   # class\n            Xlib.X.None,                          # visual\n            Xlib.X.CWEventMask | Xlib.X.CWBackPixel, # value_mask\n            event_mask=Xlib.X.ExposureMask,       # event_mask\n            background_pixel=display.screen().black_pixel # background_pixel\n        )\n        window.map_request()\n        window.map()\n        display.flush()\n        print(\"Created a simple window (will be visible briefly or not at all in some environments).\")\n        # In a real app, you'd enter an event loop here.\n        # For quickstart, we just create and then let it disappear.\n    except Xlib.error.BadMatch:\n        print(\"Could not create window (e.g., no graphical environment or visual not supported).\")\n\nfinally:\n    if 'display' in locals() and display:\n        display.close()\n        print(\"Display connection closed.\")","lang":"python","description":"This quickstart demonstrates how to connect to an X server, retrieve the root window, and print its ID. It also includes an optional step to create a basic window, which might require a running graphical environment."},"warnings":[{"fix":"Update any calls from `obj.add_extension_error()` to `obj.extension_add_error()`.","message":"The method `add_extension_error` was renamed to `extension_add_error` in version 0.32.","severity":"breaking","affected_versions":"0.32+"},{"fix":"Ensure `python-xlib` is at version 0.29 or higher when using Python 3.9 or newer. The latest version (0.33) is fully compatible.","message":"Python 3.9+ compatibility issues may arise with `python-xlib` versions older than 0.29 due to the removal of `array.array.tostring()`.","severity":"gotcha","affected_versions":"<0.29 running on Python 3.9+"},{"fix":"Verify the `DISPLAY` environment variable is correctly configured for your X server. For local sessions, `export DISPLAY=:0` or `export DISPLAY=':0.0'` is common. For remote, ensure SSH X forwarding is enabled or set it to the remote host (e.g., `export DISPLAY=remotehost:0`).","message":"When connecting to an X display, the `DISPLAY` environment variable must be correctly set, e.g., `:0` or `localhost:0`. Incorrect or missing settings will lead to `Xlib.error.DisplayNameError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.33':32 '3.6':36 'activ':38 'ad':54 'address':51 'allow':21 'applic':23 'autom':64 'bug':40 'compat':52 'desktop':63 'display':61 'extens':43,58 'fix':41 'gui':60 'interact':25 'interfac':14 'librari':3,6 'new':55 'per':49 'protocol':20,57 'provid':10 'pure':12 'python':1,4,8,13,22,35 'python-xlib':7 'receiv':39 'releas':48 'server':28 'sever':47 'support':34 'system':19 'typic':45 'updat':44 'version':31 'window':18 'x':2,5,17,27,56 'x11':59 'xlib':9 'xorg':62 'year':50","created_at":"2026-04-11T01:40:41.161654+00:00","updated_at":"2026-04-16T14:16:59.124306+00:00","problems":[{"fix":"Install the library using pip: `pip install python-xlib`","cause":"The `python-xlib` library is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'Xlib'"},{"fix":"Check if an X server is running and accessible. Verify the `DISPLAY` environment variable (e.g., `echo $DISPLAY`) is set correctly. For SSH, ensure X forwarding is enabled (`ssh -X user@host`).","cause":"The X server cannot be reached, often because the `DISPLAY` environment variable is incorrect or the X server is not running/accessible.","error":"Xlib.error.DisplayNameError: Can't open display: :0"},{"fix":"Ensure you are using `python-xlib` version 0.27 or higher, as several Python 3 compatibility fixes (including event sub-code handling) were introduced in versions 0.24 and 0.27. Upgrade `pip install --upgrade python-xlib`.","cause":"This error often indicates a Python 3 compatibility issue in older `python-xlib` versions, especially when handling event data or protocol messages where byte strings were expected but integers or vice-versa were provided.","error":"TypeError: an integer is required (got type bytes)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.33","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/python-xlib/python-xlib","docs":null,"changelog":null,"pypi":"https://pypi.org/project/python-xlib/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}