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.
Install & Compatibility
Where this runs
tested against v0.33 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.064s · 19.3MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.6s · import 0.054s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
import Xlib.display
display = Xlib.display.Display()
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.
import Xlib.display
import Xlib.X
try:
# Connect to the default display
# The DISPLAY environment variable must be set, e.g., export DISPLAY=:0
display = Xlib.display.Display()
# Get the root window of the default screen
root = display.screen().root
print(f"Successfully connected to display: {display.get_display_name()}")
print(f"Root window ID: {root.id}")
# Example: Create a simple black window
# If this causes issues in headless environments, comment out or wrap in try/except
try:
window = root.create_window(
0, 0, 200, 100, 1, # x, y, width, height, border_width
Xlib.X.CopyFromParent, # depth
Xlib.X.InputOutput, # class
Xlib.X.None, # visual
Xlib.X.CWEventMask | Xlib.X.CWBackPixel, # value_mask
event_mask=Xlib.X.ExposureMask, # event_mask
background_pixel=display.screen().black_pixel # background_pixel
)
window.map_request()
window.map()
display.flush()
print("Created a simple window (will be visible briefly or not at all in some environments).")
# In a real app, you'd enter an event loop here.
# For quickstart, we just create and then let it disappear.
except Xlib.error.BadMatch:
print("Could not create window (e.g., no graphical environment or visual not supported).")
finally:
if 'display' in locals() and display:
display.close()
print("Display connection closed.")
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.