Registry / serialization / python3-xlib

python3-xlib

JSON →
library0.15pypypi✓ verified 25d ago

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.

pip install python3-xlib
INSTALL
IMPORT
SIG · PYTHON3-XLIB
P
python3-xlib
serializationpythonv0.15
Install
2.5s avg
Import
45ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.15 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.048s · 20.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.5s · import 0.042s · 21MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Display
import Xlib.display display = Xlib.display.Display()
import Xlib display = Xlib.Display()
The Display class is part of the 'display' submodule, not directly under Xlib.

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.

import Xlib.display import Xlib.error import os try: # Attempt to connect to the X server using the DISPLAY environment variable # or a default if not set (e.g., for testing without a real X server). # For actual usage, ensure DISPLAY is correctly set (e.g., ':0' or 'localhost:0'). display_name = os.environ.get('DISPLAY', ':0') # Use ':0' as a common default display = Xlib.display.Display(display_name) print(f"Successfully connected to X display: {display_name}") # Get the root window of the default screen root_window = display.screen().root print(f"Root window ID: {root_window.id}") # Query the input focus window input_focus = display.get_input_focus() if input_focus.focus: print(f"Current input focus window ID: {input_focus.focus.id}") else: print("No specific window currently has input focus.") except Xlib.error.DisplayError as e: print(f"Error connecting to X display '{display_name}': {e}") print("HINT: Ensure an X server is running and the DISPLAY environment variable is correctly set.") except Exception as e: print(f"An unexpected error occurred: {e}") finally: if 'display' in locals() and display: display.close() print("Disconnected from X display.")
Debug
Known issues
breakingThis 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.
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`.
affects: < 0.10 (pre-python3-xlib)
gotchaConnecting 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.
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`.
affects: All versions
gotchaMany 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.
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.
affects: All versions
gotchaThe `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.
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).
affects: All versions
Errors
Common errors & fixes
Xlib.error.ConnectionError: Can't connect to display
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.
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`).
Xlib.error.BadWindow
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.
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.
ModuleNotFoundError: No module named 'Xlib'
The `python3-xlib` library or its underlying `Xlib` module is not installed in the current Python environment or is not found in `sys.path`.
fix
Install the library using pip: `pip install python3-xlib` or `pip3 install python3-xlib`.
AttributeError: 'Display' object has no attribute 'screen'
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.
fix
Call the `screen` method using parentheses to get the default screen object: `d = display.Display(); s = d.screen()` instead of `d.screen`.
Upgrade
Version history
0.15latest on PyPI · released May 31, 2014
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
Resources