aiocsv

1.4.0 verified Thu May 14 auth: no python

aiocsv is a Python library for asynchronous CSV reading and writing. It strives to be a drop-in replacement for Python's built-in `csv` module, providing `AsyncReader`, `AsyncDictReader`, `AsyncWriter`, and `AsyncDictWriter` classes. It supports Python 3.9+ and utilizes a C extension for improved performance. The library is actively maintained and currently at version 1.4.0.

pip install aiocsv

Common errors

error ModuleNotFoundError: No module named 'aiocsv' ↓

cause The 'aiocsv' package is not installed in the Python environment.

fix

Install the package using 'pip install aiocsv'.

error ImportError: cannot import name 'AsyncReader' from 'aiocsv' ↓

cause The 'aiocsv' package is installed, but the import statement is incorrect or the package version does not include 'AsyncReader'.

fix

Ensure the package is up-to-date with 'pip install --upgrade aiocsv' and use 'from aiocsv import AsyncReader'.

error TypeError: 'AsyncReader' object is not iterable ↓

cause Attempting to iterate over 'AsyncReader' without using 'async for'.

fix

Use 'async for row in AsyncReader(afp):' instead of 'for row in AsyncReader(afp):'.

error AttributeError: module 'aiocsv' has no attribute 'AsyncDictReader' ↓

cause The 'aiocsv' package version does not include 'AsyncDictReader' or the import statement is incorrect.

fix

Ensure the package is up-to-date with 'pip install --upgrade aiocsv' and use 'from aiocsv import AsyncDictReader'.

error ValueError: I/O operation on closed file. ↓

cause Attempting to read or write using 'aiocsv' after the file has been closed.

fix

Ensure that all 'aiocsv' operations are performed within the 'async with' context manager.

Warnings

gotcha When using `AsyncDictReader`, `fieldnames` can sometimes be `None`. Instead of accessing `AsyncDictReader.fieldnames` directly, use `await AsyncDictReader.get_fieldnames()` to reliably retrieve field names. ↓

fix Replace direct access to `AsyncDictReader.fieldnames` with `await reader.get_fieldnames()`.

gotcha `aiocsv` readers (`AsyncReader`, `AsyncDictReader`) expect file-like objects with an `async read(size: int)` coroutine, *not* an `AsyncIterable` over lines from a file. This differs from the standard `csv` module's behavior. ↓

fix Ensure the underlying file object provides an `async read` method (e.g., `aiofiles`). Do not pass an `AsyncIterable` of lines.

gotcha Changes to `csv.field_size_limit` are not dynamically picked up by existing `AsyncReader` instances. The field size limit is cached during `Reader` instantiation. ↓

fix If `csv.field_size_limit` needs to be changed, do so *before* creating `AsyncReader` instances, or create new `AsyncReader` instances after the change.

gotcha Files *must* be opened in text mode (`'r'` or `'w'`) and with `newline=""`. Additionally, ensure the file's line terminators match the dialect's `lineterminator`. `aiocsv` is less tolerant of mismatched newlines than the built-in `csv` module. ↓

fix Always use `mode='r'` or `mode='w'` and `newline=''` when opening files with `aiofiles` for `aiocsv`.

gotcha The `AsyncWriter.writerows()` and `AsyncDictWriter.writerows()` methods temporarily store *all* provided rows in RAM before writing them to the file. Providing a generator for extremely large datasets can lead to high memory consumption. ↓

fix For very large datasets, consider iterating and writing rows one by one using `writerow()` rather than `writerows()`, or ensure the input iterable is not excessively large.

Install compatibility last tested: 2026-05-14 v1.4.0 (up to date)

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - 0.03s 18.3M 1.8M clean

3.10 alpine (musl) - - 0.03s 18.3M 1.8M -

3.10 slim (glibc) wheel 1.5s 0.02s 19M 1.8M clean

3.10 slim (glibc) - - 0.02s 19M 1.8M -

3.11 alpine (musl) wheel - 0.06s 20.2M 2.1M clean

3.11 alpine (musl) - - 0.08s 20.2M 2.1M -

3.11 slim (glibc) wheel 1.6s 0.05s 21M 2.1M clean

3.11 slim (glibc) - - 0.06s 21M 2.1M -

3.12 alpine (musl) wheel - 0.06s 12.0M 1.9M clean

3.12 alpine (musl) - - 0.06s 12.0M 1.9M -

3.12 slim (glibc) wheel 1.5s 0.06s 13M 2.1M clean

3.12 slim (glibc) - - 0.06s 13M 2.1M -

3.13 alpine (musl) wheel - 0.05s 11.8M 2.2M clean

3.13 alpine (musl) - - 0.06s 11.7M 2.2M -

3.13 slim (glibc) wheel 1.5s 0.07s 12M 2.0M clean

3.13 slim (glibc) - - 0.06s 12M 2.0M -

3.9 alpine (musl) wheel - 0.03s 17.8M 1.8M clean

3.9 alpine (musl) - - 0.03s 17.8M 1.8M -

3.9 slim (glibc) wheel 1.8s 0.02s 18M 1.8M clean

3.9 slim (glibc) - - 0.03s 18M 1.8M -

Imports

AsyncReader
```
from aiocsv import AsyncReader
```
AsyncDictReader
```
from aiocsv import AsyncDictReader
```
AsyncWriter
```
from aiocsv import AsyncWriter
```
AsyncDictWriter
```
from aiocsv import AsyncDictWriter
```

Quickstart

This quickstart demonstrates both reading and writing CSV and TSV files asynchronously using `aiocsv` with `aiofiles`. It covers basic `AsyncReader` and `AsyncWriter` usage for list-based rows, as well as `AsyncDictReader` and `AsyncDictWriter` for dictionary-based rows, including header writing and custom delimiters.

import asyncio
import csv
import aiofiles
from aiocsv import AsyncReader, AsyncDictReader, AsyncWriter, AsyncDictWriter

async def main():
    # Create a dummy CSV file for reading
    async with aiofiles.open("example.csv", mode="w", encoding="utf-8", newline="") as afp:
        writer = AsyncWriter(afp)
        await writer.writerow(["name", "age"])
        await writer.writerows([["John", 26], ["Sasha", 42]])

    print("--- Reading simple CSV ---")
    async with aiofiles.open("example.csv", mode="r", encoding="utf-8", newline="") as afp:
        async for row in AsyncReader(afp):
            print(row)

    # Create a dummy TSV file for dict reading
    async with aiofiles.open("example.tsv", mode="w", encoding="utf-8", newline="") as afp:
        writer = AsyncDictWriter(afp, fieldnames=["name", "city"], delimiter="\t")
        await writer.writeheader()
        await writer.writerow({"name": "Alice", "city": "New York"})
        await writer.writerow({"name": "Bob", "city": "London"})

    print("\n--- Reading Dict CSV (TSV) ---")
    async with aiofiles.open("example.tsv", mode="r", encoding="utf-8", newline="") as afp:
        async for row in AsyncDictReader(afp, delimiter="\t"):
            print(row)

    # Writing new CSV file with AsyncWriter
    print("\n--- Writing simple CSV ---")
    async with aiofiles.open("output.csv", mode="w", encoding="utf-8", newline="") as afp:
        writer = AsyncWriter(afp, dialect="unix")
        await writer.writerow(["product", "price"])
        await writer.writerows([["Laptop", 1200], ["Mouse", 25], ["Keyboard", 75]])
    print("Written to output.csv")

    # Writing new CSV file with AsyncDictWriter
    print("\n--- Writing Dict CSV ---")
    async with aiofiles.open("output_dict.csv", mode="w", encoding="utf-8", newline="") as afp:
        writer = AsyncDictWriter(afp, ["item", "quantity", "status"], restval="N/A", quoting=csv.QUOTE_ALL)
        await writer.writeheader()
        await writer.writerow({"item": "Shirt", "quantity": 2, "status": "available"})
        await writer.writerows([
            {"item": "Pants", "quantity": 1},
            {"item": "Socks", "quantity": 5, "status": "low stock"}
        ])
    print("Written to output_dict.csv")

asyncio.run(main())