Registry / data / aiocsv

aiocsv

JSON →
library1.4.1pypypi✓ verified 23d ago

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
INSTALL
IMPORT
SIG · AIOCSV
A
aiocsv
datapythonv1.4.1
Install
1.7s avg
Import
44ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.4.1 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.046s · 18.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.7s · import 0.042s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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())
Debug
Known issues
gotchaWhen 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()`.
affects: All versions
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.
affects: All versions
gotchaChanges 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.
affects: All versions
gotchaFiles *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`.
affects: All versions
gotchaThe `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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiocsv'
The 'aiocsv' package is not installed in the Python environment.
fix
Install the package using 'pip install aiocsv'.
ImportError: cannot import name 'AsyncReader' from 'aiocsv'
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'.
TypeError: 'AsyncReader' object is not iterable
Attempting to iterate over 'AsyncReader' without using 'async for'.
fix
Use 'async for row in AsyncReader(afp):' instead of 'for row in AsyncReader(afp):'.
AttributeError: module 'aiocsv' has no attribute 'AsyncDictReader'
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'.
ValueError: I/O operation on closed file.
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.
Upgrade
Version history
1.4.1latest on PyPI · released May 23, 2026
Audit
Dependencies
aiofilesoptionalCommonly used for asynchronous file I/O with aiocsv, as demonstrated in official examples.
Agent activity
63 hits · last 30 days
node
52
OpenAI (training)
1
Resources