aioxlib

Human-friendly asyncio interface to the X11 protocol

aioxlib is a pure-Python library that speaks the X11 wire protocol over asyncio—without blocking the event loop and without linking to libX11.

Documentation

Online: aioxlib.readthedocs.io
Local: pip install --group docs && mkdocs serve

Installation

From within your favorite python environment:

pip install aioxlib

Quick start

The root package exposes the functional API and get_display only:

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())

Package layout

Module	Contents
`aioxlib` (root)	Constants/enums + functional API + `get_display`
`aioxlib.constants`	X11 constants and enumerations
`aioxlib.protocol`	Constants, enums, pack/unpack
`aioxlib.connection`	Socket connection, Xauthority
`aioxlib.resource`	Resource, Drawable, ResourceManager
`aioxlib.display` (Window, Screen, GC, …)	Window, Screen, GC
`aioxlib.display`	Display, Pipeline
`aioxlib.render` / `shm` / `dbe` / …	Extensions

Root functional API (selection)

Function	Role
`get_display` / `get_default_display`	Open connection
`create_window`, `map_window`, …	Windows
`events()`, `pipeline()`	Event stream / batched writes
`flush`, `query_extension`, `get_atom`, …	Display operations
`close_default_display`	Tear down default connection

Classes such as Display, Window, and EventType are not re-exported from the root; import them from their modules.

Documentation

pip install mkdocs mkdocs-material 'mkdocstrings[python]'
mkdocs serve

Examples

python examples/basic.py
python examples/functional.py

Requirements

Python ≥ 3.12
An X11 server and $DISPLAY (or an explicit URI)

License

GPLv3 or later — see LICENSE.

Author

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

Release files for aioxlib 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aioxlib 0.5.0
File	Size	Uploaded
aioxlib-0.5.0.tar.gz	98.3 kB	Aug 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aioxlib 0.5.0
File	Interpreter	ABI	Platform	Reset
aioxlib-0.5.0-py3-none-any.whl 67.5 kB Aug 26, 2026	Python 3	none	any	Details

Total release size: 165.8 kB

Release files / aioxlib-0.5.0.tar.gz

Download URL	aioxlib-0.5.0.tar.gz
Size	98.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`72c5e6c2201d961652b4235dfb6c7453879fe76ad54266f969393a67e10c4bd2`
BLAKE2b-256 checksum How to use checksums	`d98bef815506a14ff6ec2f930abc3a26947b228fe6e40e9f6b8dd21774baccd1`
Upload date	Aug 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.9`

Release files / aioxlib-0.5.0-py3-none-any.whl

Download URL	aioxlib-0.5.0-py3-none-any.whl
Size	67.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6e000efeedd46bef8f97257c8e55a83d3b473345dc2b91baa7c53f59aa1441f3`
BLAKE2b-256 checksum How to use checksums	`b52ab8985d04c1c7fa3f1cc97d73106e695913aabefba5c16e5f41999f065cb4`
Upload date	Aug 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.9`