aiofiles

25.1.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install aiofiles

Common errors

error 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.

error 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:.

error 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').

error 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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.10s 17.9M

3.10 slim (glibc) - - 0.07s 18M

3.11 alpine (musl) - - 0.18s 19.7M

3.11 slim (glibc) - - 0.14s 20M

3.12 alpine (musl) - - 0.40s 11.6M

3.12 slim (glibc) - - 0.35s 12M

3.13 alpine (musl) - - 0.40s 11.3M

3.13 slim (glibc) - - 0.36s 12M

3.9 alpine (musl) - - 0.09s 17.4M

3.9 slim (glibc) - - 0.09s 18M

Imports

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

Quickstart stale last tested: 2026-04-23

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())