Python Xlib

Python Xlib is a complete implementation of the X Window System protocol written entirely in Python, with no dependency on the native C Xlib. It lets Python programs open a connection to an X server and issue the full range of X11 requests - creating and manipulating windows, reading input events, querying the display, working with atoms and properties, and using common X extensions.

Because it speaks the wire protocol directly, it is portable across Python 2 and 3 and serves as the foundation for many higher-level tools that need low-level control of the Linux/Unix desktop, including input-automation and global-hotkey libraries. It exposes both a high-level object interface and lower-level protocol access for callers that need fine-grained control.

What You Get

• A pure-Python X11 protocol client requiring no native Xlib
• A high-level Display object for connecting to and querying an X server
• Window creation, mapping, and manipulation APIs
• Event reading and input handling (keyboard, pointer)
• Support for common X extensions under Xlib.ext
• Python 2 and 3 compatibility

Common Use Cases

• Building global hotkey or input-automation tools on Linux
• Programmatically querying and manipulating windows on an X desktop
• Reading keyboard and pointer events at a low level
• Serving as the X11 backend for higher-level automation libraries

Under The Hood

Architecture - The Xlib package layers a protocol implementation under an object model. Xlib/protocol encodes and decodes X11 requests, replies, and events over the wire; display.py provides the high-level Display connection object; xobject/ models resources like windows, pixmaps, and cursors; and ext/ implements optional X extensions. Constant and atom tables (X.py, Xatom.py, XK.py, keysymdef/) mirror the X11 headers, and support/ handles platform connection details such as Unix sockets.

Tech Stack - Pure Python with no compiled components, targeting both Python 2.7 and Python 3. Packaging is via setuptools (setup.py/setup.cfg), with tox for multi-version test runs and a small requirements/dev-requirements split. It talks to the X server directly over the socket protocol rather than binding to libX11.

Code Quality - The test/ directory contains a meaningful suite covering byte-level views, big- and little-endian event and request encoding, struct packing, and the resource database parser, with generated fixtures under test/gen. Coverage is tracked via codecov. The codebase is long-established and stable, though recent development activity is low.

API Design - Callers typically start with Xlib.display.Display() and work through returned window and resource objects, which is ergonomic for high-level tasks. The lower protocol layer is available for fine-grained control but exposes the full complexity of X11, so the learning curve reflects the underlying protocol more than the wrapper. Bundled examples in examples/ help demonstrate common patterns.