liburing 2026.3.25

Liburing is Python + Zig wrapper around C Liburing, which is a helper to setup and tear-down io_uring instances.

Liburing

Liburing is Python + Zig wrapper around C Liburing, which is a helper to setup and tear-down io_uring instances.

• Fast & scalable asynchronous I/O (storage, networking, ...) interface.
• io_uring reduces number of syscalls overhead & context switches, thus improving speed.

Good(old) documentation Lord of the io_uring

Requires

• Linux 6.14+
• Python 3.10+

Includes (battery)

• C liburing 2.15+

Install, update & uninstall (Alpha)

Use pip to install, upgrade & uninstall Python wrapper

python3 -m pip install liburing             # install

python3 -m pip install --upgrade liburing   # upgrade

python3 -m pip uninstall liburing           # uninstall

To compile & install directly from GitHub

# note: make sure you have Zig 0.15.2 installed on your system.

cd /tmp
git clone --recurse-submodules https://github.com/YoSTEALTH/Liburing
cd Liburing

python3 -m pip install pyoz
python3 -m pyoz build
python3 -m pip install dist/*.whl

# uninstall
python3 -m pip uninstall liburing pyoz

To find out all the class, functions and definitions

import liburing

# To see all the importable names
print(dir(liburing))

# To see all the help docs
help(liburing)

Find out which io_uring operations is supported by the kernel

# example/probe.py
import liburing

for k, v in liburing.probe().items():
    print(k, v)

Simple File Example

# example/open_write_read_close.py
from liburing import O_CREAT, O_RDWR, Ring, Cqe, io_uring_get_sqe, \
                     io_uring_prep_open, io_uring_prep_write, io_uring_prep_read, \
                     io_uring_prep_close, io_uring_submit, io_uring_wait_cqe, \
                     io_uring_cqe_seen, io_uring_queue_init, io_uring_queue_exit, trap_error


def open(ring, cqe, path, flags):
    sqe = io_uring_get_sqe(ring)  # sqe(submission queue entry)
    io_uring_prep_open(sqe, path, flags)
    # set submit entry identifier as `1` which is returned back in `cqe.user_data`
    # so you can keep track of submit/completed entries.
    sqe.user_data = 1
    return _submit_and_wait(ring, cqe)  # returns fd


def write(ring, cqe, fd, data):
    sqe = io_uring_get_sqe(ring)
    io_uring_prep_write(sqe, fd, data)
    sqe.user_data = 2
    return _submit_and_wait(ring, cqe)  # returns length(s) of bytes written


def read(ring, cqe, fd, length):
    buffer = bytearray(length)  # where read data will be stored
    sqe = io_uring_get_sqe(ring)
    io_uring_prep_read(sqe, fd, buffer)
    sqe.user_data = 3
    _submit_and_wait(ring, cqe)  # get actual length of file read.
    return buffer


def close(ring, cqe, fd):
    sqe = io_uring_get_sqe(ring)
    io_uring_prep_close(sqe, fd)
    sqe.user_data = 4
    _submit_and_wait(ring, cqe)  # no error means success!


def _submit_and_wait(ring, cqe):
    io_uring_submit(ring)  # submit entry
    io_uring_wait_cqe(ring, cqe)  # wait for entry to finish
    entry = cqe[0]
    result = trap_error(entry.res)  # auto raise appropriate exception if failed
    # note `entry.res` returns results, if ``< 0`` its an error, if ``>= 0`` its the value

    # done with current entry so clear it from completion queue.
    io_uring_cqe_seen(ring, entry)
    return result  # type: int


def main():
    ring = Ring()
    cqe = Cqe()  # completion queue entry
    try:
        io_uring_queue_init(8, ring)

        fd = open(ring, cqe, '/tmp/liburing-test-file.txt', O_CREAT | O_RDWR)
        print('fd:', fd)

        length = write(ring, cqe, fd, b'hi... bye!')
        print('wrote:', length)

        content = read(ring, cqe, fd, length)
        print('read:', content)

        close(ring, cqe, fd)
        print('closed.')
    finally:
        io_uring_queue_exit(ring)


if __name__ == '__main__':
    main()

Note

• This project has been moved to using Zig as back-end, thus leading to breaking changes from previous release.
• Try using latest Linux if possible to enable all io_uring features.

Other Projects

• PyOZ

License

Free, Public Domain (CC0). Read more