Install & Compatibility
Where this runs
tested against v0.8.5 · 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
py 3.10
✕ build_error
✓ 5.88s
py 3.11
✕ build_error
✓ 5.16s
py 3.12
✕ build_error
✓ 5.08s
py 3.13
✕ build_error
4/8 runs
py 3.9
✕ build_error
✓ 6.9s
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
clevercsv
✓ import clevercsv
Commonly imported as a direct replacement for the built-in `csv` module.
reader
✓ import clevercsv
reader = clevercsv.reader(file, dialect)
✗ import csv
reader = csv.reader(file, dialect)
CleverCSV provides a compatible `reader` object, often preferred for its improved dialect detection.
read_table
✓ import clevercsv
table = clevercsv.read_table('my_file.csv')
A high-level function for automatically detecting dialect and encoding, returning data as a list of lists.
read_dataframe
✓ import clevercsv
df = clevercsv.read_dataframe('my_file.csv')
Automatically detects dialect and encoding, then uses Pandas to read into a DataFrame. Requires `pandas`.
This quickstart demonstrates how to use CleverCSV to read a messy CSV file, automatically detecting its dialect, using both the high-level `read_table` function and by employing `clevercsv.Sniffer` as a drop-in replacement for the standard library's `csv.Sniffer`.
import clevercsv
import os
# Create a dummy messy CSV file for demonstration
csv_content = 'col1;col2;col3\nvalue1;"value,2";value3\n4;5;6\n'
file_path = 'messy_data.csv'
with open(file_path, 'w', newline='', encoding='utf-8') as f:
f.write(csv_content)
try:
# Use read_table to automatically detect the dialect and load the data
rows = clevercsv.read_table(file_path)
print(f"Loaded {len(rows)} rows with detected dialect:")
for row in rows:
print(row)
# Demonstrate drop-in replacement for standard csv module usage
with open(file_path, 'r', newline='') as csvfile:
# Sniff the dialect using CleverCSV's improved sniffer
dialect = clevercsv.Sniffer().sniff(csvfile.read(1024))
csvfile.seek(0)
reader = clevercsv.reader(csvfile, dialect)
sniffer_rows = list(reader)
print(f"\nLoaded {len(sniffer_rows)} rows using CleverCSV.Sniffer:")
for row in sniffer_rows:
print(row)
finally:
# Clean up the dummy file
if os.path.exists(file_path):
os.remove(file_path)
clevercsv --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'clevercsv'
The 'clevercsv' package has not been installed in your current Python environment.
fixRun `pip install clevercsv` in your terminal to install the package.
TypeError: expected file-like object, got str
You are attempting to pass a string representing a file path directly to `clevercsv.reader()` or `clevercsv.writer()`, but these functions expect an opened file object.
fixOpen the CSV file using `open()` in read ('r') or write ('w') mode and pass the resulting file object: `with open('your_file.csv', 'r', newline='') as f: reader = clevercsv.reader(f)`. clevercsv: command not found
The `clevercsv` command-line tool is not accessible in your system's PATH, typically because it was not installed correctly or your virtual environment is not activated.
fixEnsure `clevercsv` is installed and your virtual environment (if any) is active. Alternatively, run the command-line tool as a Python module: `python -m clevercsv <command> [options] <file>`.
AttributeError: type object 'DataFrame' has no attribute 'read_csv'
This error often occurs when attempting to call `read_csv` on a Pandas DataFrame object instead of the top-level Pandas module, or when a local file/module named 'pandas.py' shadows the actual Pandas library. Users migrating from standard Pandas workflows to `clevercsv` might encounter similar logical errors if they try to apply Pandas methods incorrectly after using `clevercsv` to get a DataFrame.
fixIf you intend to read a CSV into a Pandas DataFrame using CleverCSV's enhanced dialect detection, use `clevercsv.csv2df('your_file.csv')`. If you are using standard Pandas, ensure you import pandas as `import pandas as pd` and call `pd.read_csv('your_file.csv')`. Upgrade
Version history
0.8.5latest on PyPI · released May 11, 2026
Audit
Dependencies
pandasoptionalRequired for functions like `read_dataframe` to load CSV data directly into a Pandas DataFrame.
tabviewoptionalRequired for the `clevercsv explore` command-line tool, which provides an interactive viewer.