caio

What it is and what it does

Caio is a Python wrapper around async file I/O primitives, exposing four backends with automatic selection based on platform and kernel capabilities. On Linux, it can use io_uring (kernel ≥5.6) for zero-syscall completions via shared ring buffers, kernel AIO (kernel ≥4.18) for direct I/O, or a thread pool for broader compatibility. On other platforms or as a universal fallback, it provides a pure-Python implementation. The library integrates with asyncio, allowing file operations like read, write, and fdsync to be awaited as coroutines rather than blocking.

The package targets developers building high-performance async applications that need non-blocking file I/O without the complexity of managing multiple I/O backends manually. It handles backend selection transparently via environment variable or direct import, and gracefully degrades when advanced kernel features are unavailable or blocked (e.g., by container seccomp filters). With no external runtime dependencies and support for Python 3.10 through 3.14, it integrates cleanly into modern async codebases.

Use it for

• High-throughput async services that read or write files concurrently without blocking the event loop
• Containerized applications needing portable async file I/O that falls back from io_uring to thread pool when seccomp blocks kernel features
• Performance-critical workloads on Linux that can exploit io_uring or kernel AIO for reduced syscall overhead
• Async data processing pipelines that need to coordinate file I/O with other async operations via asyncio.gather
• Applications requiring explicit control over I/O backend selection for testing or environment-specific optimization

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

caio on PyPI

Before you install

Low friction install with no runtime dependencies. Actively maintained with a recent release (10 days old) and steady repository activity.

Requires Python 3.10+. On Linux, io_uring backend needs kernel ≥5.6; linux_aio needs kernel ≥4.18. Containers may block io_uring via seccomp; use CAIO_IMPL=thread or CAIO_IMPL=python as fallback.

License in practice

Licensed under Apache-2.0 (permissive), allowing use in most commercial and open-source projects without significant restrictions.

Quickstart

import asyncio
from caio import AsyncioContext

async def main():
    ctx = AsyncioContext(max_requests=128)
    with open('test.file', 'wb+') as fp:
        fd = fp.fileno()
        await ctx.write(b'Hello', fd, offset=0)
        data = await ctx.read(32, fd, offset=0)
        print(data)

asyncio.run(main())

Package facts

Evidence: caio-0.12.2-py3-none-any.whl

Tags

More Software Development packages

See also aiofile · kubernetes-asyncio · gcloud-aio-storage · gcloud-aio-bigquery · aiooss2 · aiomultiprocess · aiofiles · gcloud-aio-datastore · pyserial-asyncio · nono-py