{"id":1054,"library":"caio","title":"Asynchronous File IO (caio)","description":"caio is a Python library providing asynchronous file I/O for Linux, macOS, and Windows. It offers Python bindings for Linux AIO API, including `io_uring`, and provides fallback mechanisms for other platforms using threads or pure Python. Currently at version 0.9.25, the library is actively maintained with regular updates.","status":"active","version":"0.9.25","language":"python","source_language":"en","source_url":"https://github.com/mosquito/caio","tags":["asyncio","file-io","linux-aio","io_uring","asynchronous","cross-platform"],"install":[{"cmd":"pip install caio","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"This import automatically selects the best available backend (linux_uring → linux_aio → thread_aio → python_aio).","symbol":"AsyncioContext","correct":"from caio import AsyncioContext"},{"note":"Use this to explicitly force the `io_uring` backend on Linux kernels >= 5.6.","symbol":"AsyncioContext (linux_uring)","correct":"from caio.linux_uring_asyncio import AsyncioContext"},{"note":"Use this to explicitly force the `linux_aio` backend on Linux kernels >= 4.18.","symbol":"AsyncioContext (linux_aio)","correct":"from caio.linux_aio_asyncio import AsyncioContext"},{"note":"Use this to explicitly force the thread-based backend, which is portable.","symbol":"AsyncioContext (thread)","correct":"from caio.thread_aio_asyncio import AsyncioContext"},{"note":"Use this to explicitly force the pure Python backend, which requires no C extension.","symbol":"AsyncioContext (python)","correct":"from caio.python_aio_asyncio import AsyncioContext"}],"quickstart":{"code":"import asyncio\nimport os\nfrom caio import AsyncioContext\n\nasync def main():\n    # Ensure a dummy file exists for the example\n    file_path = \"test.file\"\n    with open(file_path, \"wb+\") as f: # Create or truncate the file\n        f.write(b\"\")\n\n    ctx = AsyncioContext(max_requests=128)\n    fd = os.open(file_path, os.O_RDWR | os.O_CREAT)\n\n    try:\n        # Execute one write operation\n        await ctx.write(b\"Hello world\", fd, offset=0)\n        print(f\"Wrote: Hello world\")\n\n        # Execute one read operation\n        read_data = await ctx.read(32, fd, offset=0)\n        print(f\"Read: {read_data.decode()}\")\n\n        # Execute one fdsync operation\n        await ctx.fdsync(fd)\n        print(\"File synchronized.\")\n\n        # Execute multiple writes concurrently\n        op1 = ctx.write(b\"Hello from \", fd, offset=0)\n        op2 = ctx.write(b\"async world\", fd, offset=11)\n        await asyncio.gather(op1, op2)\n        print(\"Concurrent writes completed.\")\n\n        read_data_concurrent = await ctx.read(32, fd, offset=0)\n        print(f\"Read after concurrent writes: {read_data_concurrent.decode()}\")\n\n    finally:\n        os.close(fd)\n        os.remove(file_path)\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to use `caio` with `asyncio` to perform basic asynchronous file operations like writing, reading, and synchronizing. It also shows how to execute multiple write operations concurrently. A temporary file is created and cleaned up for the demonstration."},"warnings":[{"fix":"To fix this, run containers with `--security-opt seccomp=unconfined` (Docker/Podman) or set `securityContext.seccompProfile.type: Unconfined` (Kubernetes).","message":"The `io_uring` backend might be blocked by `seccomp` filters in container environments like Docker, Podman, or Kubernetes. This can lead to `ImportError` when `io_uring_setup(2)` returns `ENOSYS`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Linux kernel is 4.18 or newer for optimal performance with native AIO. Alternatively, explicitly select a backend using the `CAIO_IMPL` environment variable (`CAIO_IMPL=thread` or `CAIO_IMPL=python`) or by importing a specific backend directly (e.g., `from caio.thread_aio_asyncio import AsyncioContext`).","message":"Native Linux AIO implementation requires a kernel version of 4.18 or newer. If an older kernel is detected, `caio` will fall back to a thread-based or pure Python implementation, which might have different performance characteristics.","severity":"gotcha","affected_versions":"All versions when using Linux AIO backend"},{"fix":"Use `from caio import AsyncioContext` for automatic backend selection. For explicit control, set the `CAIO_IMPL` environment variable (e.g., `CAIO_IMPL=uring`) or create a `default_implementation` file with the desired backend name (e.g., `uring`).","message":"Direct imports of specific backend implementations (e.g., `from caio.linux_aio_asyncio import AsyncioContext`) were previously the primary way to force a backend. While still possible, it is now recommended to let `caio` pick the best available backend automatically via `from caio import AsyncioContext` or to use the `CAIO_IMPL` environment variable or a `default_implementation` file for global control.","severity":"deprecated","affected_versions":"Prior to 0.7.0, direct imports were more common. Since 0.7.0+, `CAIO_IMPL` and `default_implementation` are preferred."}],"env_vars":null,"search_vec":"'0.9.25':45 'activ':49 'aio':25,60 'api':26 'asynchron':1,11,63 'asyncio':54 'bind':22 'caio':4,5 'cross':65 'cross-platform':64 'current':42 'fallback':32 'file':2,12,56 'file-io':55 'i/o':13 'includ':27 'io':3,28,57,61 'librari':9,47 'linux':15,24,59 'linux-aio':58 'maco':16 'maintain':50 'mechan':33 'offer':20 'platform':36,66 'provid':10,31 'pure':40 'python':8,21,41 'regular':52 'thread':38 'updat':53 'ure':29,62 'use':37 'version':44 'window':18","created_at":"2026-04-01T06:44:52.271540+00:00","updated_at":"2026-04-16T01:19:31.224836+00:00","problems":[{"fix":"Install the `libaio-dev` (Debian/Ubuntu) or `libaio` (Red Hat/Fedora) package: `sudo apt-get install libaio-dev` or `sudo yum install libaio`. Ensure your Linux kernel is compatible (typically 4.18+ for native AIO) and the filesystem supports it. Alternatively, explicitly use a different backend like `thread_aio` or `python_aio` by setting the `CAIO_IMPL` environment variable (e.g., `CAIO_IMPL=thread python your_app.py`) or importing directly (e.g., `from caio.thread_aio_asyncio import AsyncioContext`).","cause":"This error occurs when the `linux_aio` backend attempts to initialize the AIO context via `io_setup` but fails, often due to missing `libaio` development libraries or an incompatible kernel/filesystem.","error":"ImportError: Error on io_setup with code 22"},{"fix":"Run your container with elevated security privileges that allow `io_uring` syscalls. For Docker/Podman, use `docker run --security-opt seccomp=unconfined ...` or provide a custom `seccomp` profile that permits `io_uring_enter`, `io_uring_register`, and `io_uring_setup` syscalls. For Kubernetes, configure `securityContext.seccompProfile.type: Unconfined`.","cause":"This `ImportError` indicates that the `io_uring` system call is blocked, most commonly in containerized environments (Docker, Podman, Kubernetes) due to restrictive `seccomp` filters.","error":"ImportError: io_uring_setup(2) returns ENOSYS (Operation not permitted)"},{"fix":"Ensure `caio` is installed in your active Python environment using pip: `pip install caio`. If using virtual environments, activate the correct environment before installation. Verify the Python interpreter being run is the one where `caio` was installed.","cause":"This common Python error means the `caio` package is not installed in the Python environment being used, or the Python interpreter cannot find it in its search path.","error":"ModuleNotFoundError: No module named 'caio'"}],"ecosystem":"pypi","meta_description":null,"install_score":97,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.25","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mosquito/caio","docs":null,"changelog":null,"pypi":"https://pypi.org/project/caio/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}