aioxlib

Human-friendly asyncio interface to the X11 protocol

aioxlib is a pure-Python library that talks the X11 wire protocol over asyncio.
It aims to make working with X displays, windows, graphics contexts, events, and images feel natural in modern async Python code—without blocking the event loop.

Inspired by the style of linuxpy (also by the same author), it provides a clean, high-level API while still exposing the underlying protocol details when you need them.

Features

• Fully asynchronous connection to the X server (Unix socket or TCP)
• High-level objects: Display, Screen, Window, GC, resources
• Event stream via async for event in display.events()
• Window creation, mapping, attributes, WM properties (WM_NAME, WM_PROTOCOLS, …)
• Graphics Context (GC) drawing: rectangles, text (put_text), images
• MIT-SHM support for high-performance image transfer
• Atom interning, extensions querying, fonts listing
• Python ≥ 3.12, GPLv3
• No external dependencies
• Code in a single file

Installation

From within your favorite python environment:

pip install aioxlib

Quick start

import asyncio
import aioxlib


async def main():
    display = await aioxlib.get_display()
    async with display:
        screen = display.default_screen()
        wnd = await screen.create_window(width=640, height=480)
        await wnd.show()
        await wnd.set_name("Hello from aioxlib")

        # Handle window close
        protocols = await display.get_atom("WM_PROTOCOLS")
        delete = await display.get_atom("WM_DELETE_WINDOW")
        await wnd.set_wm_protocols([delete])

        async for event in display.events():
            if (
                event["code"] == aioxlib.Event.ClientMessage
                and event["type"] == protocols
                and event["data"][0] == delete
            ):
                break


asyncio.run(main())

Examples

The examples/ directory contains several demos:

Run any of them with:

python examples/basic.py

API overview

display = await aioxlib.get_display()          # or get_display(":0")
async with display:
    screen = display.default_screen()

    wnd = await screen.create_window(...)      # or display.create_window(...)
    await wnd.show()
    await wnd.set_name("…")
    await wnd.set_wm_protocols([...])

    gc = await wnd.create_gc(foreground=…, background=…)
    await gc.poly_fill_rectangles([...])
    await gc.put_text(x, y, "text")
    await wnd.draw_image(gc, x, y, w, h, depth, data)

    async for event in display.events():
        ...

Events are plain dicts with a "code" field matching aioxlib.Event.*.

Requirements

• Python ≥ 3.12
• An X11 server (Xorg, Xwayland, …)
• $DISPLAY set (or pass the display string explicitly)

License

GPLv3 or later — see LICENSE.

Author

José Tiago Macara Coutinho
https://codeberg.org/tiagocoutinho

Early beta (v0.0.2). Feedback and contributions welcome!