{"id":1074,"library":"aiofile","title":"aiofile","description":"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.","status":"active","version":"3.9.0","language":"python","source_language":"en","source_url":"http://github.com/mosquito/aiofile","tags":["async","file I/O","asyncio","non-blocking"],"install":[{"cmd":"pip install aiofile","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.8 or newer for version 3.9.0.","package":"python"}],"imports":[{"note":"Use this helper for a high-level, file-like interface similar to Python's built-in open().","symbol":"async_open","correct":"from aiofile import async_open"},{"note":"This is a low-level interface; direct usage requires explicit offset management for read/write operations.","symbol":"AIOFile","correct":"from aiofile import AIOFile"}],"quickstart":{"code":"import asyncio\nfrom aiofile import async_open\n\nasync def main():\n    # Write to a file asynchronously\n    async with async_open(\"hello.txt\", mode=\"w+\") as f:\n        await f.write(\"Hello, aiofile!\")\n        await f.seek(0)\n        content = await f.read()\n        print(f\"Read: {content}\")\n\n    # Read a file line by line asynchronously\n    async with async_open(\"hello.txt\", mode=\"r\") as f:\n        async for line in f:\n            print(f\"Line: {line.strip()}\")\n\nasyncio.run(main())","lang":"python","description":"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."},"warnings":[{"fix":"Prefer `async with async_open(...) as f:` for typical file operations. If using `AIOFile`, ensure you manage `offset` for each read/write call.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For 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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions on Linux"},{"fix":"Use `async for line in file_obj:` (where `file_obj` is from `async_open`) for efficient line-by-line processing, leveraging the `LineReader`.","message":"When 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.","severity":"gotcha","affected_versions":">=3.7.0"},{"fix":"Always use `aiofile.async_open` or other `aiofile` asynchronous primitives for file I/O within an `asyncio` context to ensure non-blocking operations.","message":"Using 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T23:33:22.177Z","next_check":"2026-07-01T00:00:00.000Z","problems":[{"fix":"Install the 'aiofile' package using pip: 'pip install aiofile'.","cause":"The 'aiofile' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'aiofile'"},{"fix":"Ensure that the 'AsyncFileIO' object is correctly instantiated and that the 'write' method is available.","cause":"Attempting to use a method that does not exist on the 'AsyncFileIO' object.","error":"AttributeError: 'AsyncFileIO' object has no attribute 'write'"},{"fix":"Verify the correct import statement and ensure that the 'AIOFile' class is defined in the 'aiofile' module.","cause":"The 'AIOFile' class is not available in the 'aiofile' module.","error":"ImportError: cannot import name 'AIOFile' from 'aiofile'"},{"fix":"Use 'await' to resolve the coroutine before iterating over its result.","cause":"Attempting to iterate over a coroutine object without awaiting it.","error":"TypeError: 'coroutine' object is not iterable"},{"fix":"Ensure that the event loop is running and not closed when performing asyncio operations.","cause":"Trying to run an asyncio operation after the event loop has been closed.","error":"RuntimeError: Event loop is closed"}],"ecosystem":"pypi","meta_description":null,"install_score":97,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.9.0","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"3.9.0","pypi_latest":"3.9.0","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.23,"mem_mb":7.2,"disk_size":"18.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":7.2,"disk_size":"18.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.18,"mem_mb":7.2,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":7.2,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.31,"mem_mb":8.3,"disk_size":"19.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":8.3,"disk_size":"19.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.7,"import_time_s":0.29,"mem_mb":8.5,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":8.5,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.51,"mem_mb":8.4,"disk_size":"11.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.59,"mem_mb":8.4,"disk_size":"11.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.49,"mem_mb":8.4,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":8.4,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.54,"mem_mb":8.8,"disk_size":"11.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.59,"mem_mb":8.8,"disk_size":"11.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.49,"mem_mb":8.8,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.56,"mem_mb":8.8,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aiofile","exit_code":1,"wheel_type":null,"failure_reason":"build_error","import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aiofile","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.9,"import_time_s":0.19,"mem_mb":7.2,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aiofile","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":7.2,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}