aioxlib

Human-friendly asyncio interface to the X11 protocol

aioxlib is a pure-Python, asyncio-native client for the X11 wire protocol. Open displays, create windows, draw with GCs and the RENDER extension, and stream events — without blocking the event loop and without linking to libX11 or xcb.

Examples shipped with the library: Game of Life · 3D wireframe

Why aioxlib?

Inspired by linuxpy (same author): a clean high-level API when you want it, full protocol detail when you need it.

Requirements

• Python ≥ 3.12
• An X server (local or remote) and network/socket access to it ($DISPLAY or an explicit URI)

No third-party Python packages are required at runtime.

Installation

pip install aioxlib

Quick start

Functional API (simplest)

import asyncio
import aioxlib


async def main():
    wnd = await aioxlib.create_window(640, 480, title="Hello from aioxlib")
    await wnd.show()

    async for event in aioxlib.events():
        if wnd.is_delete_window(event):
            break


asyncio.run(main())

Explicit display (object API)

import asyncio
import aioxlib


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

        async for event in display.events():
            if wnd.is_delete_window(event):
                break


asyncio.run(main())

Features

• Windows & drawing — create/map/configure windows, GCs, polylines, rectangles, arcs, text, images
• Events — non-blocking async for event in display.events() stream
• Properties & atoms — WM_NAME, protocols, custom properties
• Extensions — BIG-REQUESTS, RENDER, MIT-SHM, DBE, GLX, RANDR, DRI3, Present
• Pipeline — batch requests with async with display.pipeline(): …
• Protocol transparent — opcodes, pack/unpack helpers stay accessible

Examples

# clone the repo, then:
python examples/basic.py
python examples/game_of_life.py   # Conway's Life (numpy)
python examples/3d.py             # rotating 3D mesh
python examples/video_shm_dbe.py  # shared memory + double buffering

Package layout

Classes such as Display, Window, and EventType are imported from their modules (or from the root where re-exported).

Root functional API (selection)

Documentation

• Online: aioxlib.readthedocs.io
• Local:

pip install --group docs   # or: pip install mkdocs mkdocs-material 'mkdocstrings[python]'
mkdocs serve

License

GPLv3 or later — see LICENSE.

Author

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