aiofile provides real asynchronous file operations for asyncio applications. It addresses the blocking nature of ordinary file I/O by delegating operations to a separate thread pool, ensuring that file operations do not block the asyncio event loop. The library is Apache2 licensed, currently at version 3.9.0, and maintains a stable development status.
Install & Compatibility
Where this runs
tested against v3.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✓ 1.85s
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
async_open
✓ from aiofile import async_open
Use this helper for a high-level, file-like interface similar to Python's built-in open().
AIOFile
✓ from aiofile import AIOFile
This is a low-level interface; direct usage requires explicit offset management for read/write operations.
This quickstart demonstrates how to asynchronously write to and read from a file using `aiofile.async_open`, which provides a familiar file-like interface. It also shows asynchronous iteration for reading files line by line.
import asyncio
from aiofile import async_open
async def main():
# Write to a file asynchronously
async with async_open("hello.txt", mode="w+") as f:
await f.write("Hello, aiofile!")
await f.seek(0)
content = await f.read()
print(f"Read: {content}")
# Read a file line by line asynchronously
async with async_open("hello.txt", mode="r") as f:
async for line in f:
print(f"Line: {line.strip()}")
asyncio.run(main())
Debug
Known issues
gotchaThe low-level `aiofile.AIOFile` object does not maintain an internal file pointer. When using `AIOFile` directly, you must explicitly pass the `offset` argument for each `read` or `write` operation. For a more standard file-like behavior with an implicit pointer, use the `aiofile.async_open` helper.fixPrefer `async with async_open(...) as f:` for typical file operations. If using `AIOFile`, ensure you manage `offset` for each read/write call.
affects: All versions
gotchaThe native Linux AIO implementation used by `aiofile` (via `caio`) cannot perform asynchronous operations on special file systems like `/proc/` or `/sys/`. Attempts to use `aiofile` on these file types may fail.fixFor operations on special file systems, you might need to configure `caio` to use its thread-based or pure Python implementations by setting the `CAIO_IMPL` environment variable (e.g., `CAIO_IMPL=thread`) or falling back to synchronous I/O if appropriate.
affects: All versions on Linux
gotchaWhen reading files line by line, especially with many small lines, repeatedly calling `await file_obj.readline()` on an `async_open` object can be suboptimal. Since version 3.7.0, `__aiter__` on an `async_open` object returns a `LineReader`, which is more efficient for line-based iteration.fixUse `async for line in file_obj:` (where `file_obj` is from `async_open`) for efficient line-by-line processing, leveraging the `LineReader`.
affects: >=3.7.0
gotchaUsing Python's built-in `open()` function or other synchronous file I/O operations directly within an `asyncio` application's event loop will block the entire loop, negating the benefits of asynchronous programming and potentially freezing your application.fixAlways use `aiofile.async_open` or other `aiofile` asynchronous primitives for file I/O within an `asyncio` context to ensure non-blocking operations.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiofile'
The 'aiofile' package is not installed in the Python environment.
fixInstall the 'aiofile' package using pip: 'pip install aiofile'.
AttributeError: 'AsyncFileIO' object has no attribute 'write'
Attempting to use a method that does not exist on the 'AsyncFileIO' object.
fixEnsure that the 'AsyncFileIO' object is correctly instantiated and that the 'write' method is available.
ImportError: cannot import name 'AIOFile' from 'aiofile'
The 'AIOFile' class is not available in the 'aiofile' module.
fixVerify the correct import statement and ensure that the 'AIOFile' class is defined in the 'aiofile' module.
TypeError: 'coroutine' object is not iterable
Attempting to iterate over a coroutine object without awaiting it.
fixUse 'await' to resolve the coroutine before iterating over its result.
RuntimeError: Event loop is closed
Trying to run an asyncio operation after the event loop has been closed.
fixEnsure that the event loop is running and not closed when performing asyncio operations.
Audit
Dependencies
pythonrequiredRequires Python 3.8 or newer for version 3.9.0.