aiofiles

25.1.0 · active · verified Sat Apr 11

aiofiles is a Python library that provides asynchronous file operations for asyncio applications, enabling non-blocking file I/O. The current version is 25.1.0, released on October 9, 2025. The library follows a regular release cadence, with updates approximately every few months.

Common errors

```
ModuleNotFoundError: No module named 'aiofiles'
```
cause The `aiofiles` library is not installed in the Python environment where the code is being run.

fix Install the library using pip: `pip install aiofiles`.
```
AttributeError: __enter__
```
cause This error typically occurs when attempting to use `aiofiles.open()` with a synchronous `with` statement instead of an asynchronous `async with` statement, as `aiofiles.open()` returns an asynchronous context manager.

fix Ensure that `aiofiles.open()` is used within an `async` function and with the `async with` keyword: `async with aiofiles.open('filename', mode='r') as f:`.
```
RuntimeWarning: coroutine '...' was never awaited
```
cause An asynchronous function (coroutine) from `aiofiles` was called, but its returned coroutine object was not explicitly `await`ed, meaning its execution was never scheduled or completed.

fix Always `await` calls to `aiofiles` functions and methods that return coroutines, such as `aiofiles.open()`, `file.read()`, `file.write()`, or `aiofiles.os.remove()`: `await file.read()` or `await aiofiles.os.remove('file.txt')`.
```
AttributeError: module 'aiofiles.os' has no attribute 'path'
```
cause Developers often try to access submodules or functions like `path` directly through `aiofiles.os` expecting it to mirror the entire standard `os` module, but `aiofiles.os` only provides asynchronous versions of some `os` functions directly.

fix Import `os.path` separately for path-related operations, as it is synchronous and generally safe to use outside of `aiofiles.os`: `import os.path` and then `os.path.join(...)`.

Warnings

breaking Python 3.8 support dropped in aiofiles 25.1.0
Fix: Upgrade to Python 3.9 or later to continue using aiofiles.
gotcha Ensure to use 'async with' when working with aiofiles to avoid 'AttributeError: __enter__' errors
Fix: Always use 'async with' for asynchronous context management with aiofiles.
gotcha FileNotFoundError: The specified file does not exist when using aiofiles.open().
Fix: Ensure that the file specified in aiofiles.open() exists at the given path in the execution environment.
gotcha FileNotFoundError occurs when the specified file does not exist at the given path for aiofiles.open().
Fix: Ensure that the file specified in `aiofiles.open()` (e.g., 'example.txt') exists in the directory where the script is being executed, or provide the full absolute path to the file.

Install

pip install aiofiles Install aiofiles

Imports

open
```
from aiofiles import open
```
Ensure to import 'open' from 'aiofiles' for asynchronous file operations

Quickstart

This example demonstrates how to asynchronously read a file using aiofiles. The 'open' function from aiofiles is used to open the file, and 'await' is used to read its contents without blocking the event loop.

import aiofiles
import asyncio

async def read_file():
    async with aiofiles.open('example.txt', mode='r') as f:
        contents = await f.read()
        print(contents)

asyncio.run(read_file())

view raw JSON →