csvkit

library2.2.0pypypi✓ verified 86d ago

csvkit is a suite of powerful command-line tools for working with CSV files. It enables users to convert, clean, analyze, and process tabular data efficiently from the command line. The current version is 2.2.0. Its release cadence is moderate, with major versions often representing significant architectural changes.

data devops

pip install csvkit

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · CSVKIT

csvkit

datapythonv2.2.0

Install

4.8s avg

Import

431ms

Disk

82MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.2.0 · 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.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.449s · 82.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.8s · import 0.414s · 81MB

82MB installed

● package 82MB

Code

Verified usage

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

agate

✓ import agate

csvkit is primarily a command-line utility suite. For programmatic access to tabular data processing in Python, the underlying `agate` library is the commonly imported and used component, which `csvkit` builds upon for its CLI tools. Direct programmatic use of csvkit's internal modules is less common and not part of its public API.

This quickstart demonstrates how to use csvkit's command-line tools (`csvlook` and `csvsql`) programmatically from Python via the `subprocess` module. It creates a sample CSV, pretty-prints it, and then queries it.

import subprocess import os # Create a dummy CSV file csv_content = "name,age\nAlice,30\nBob,24\nCharlie,35" file_path = "example.csv" with open(file_path, "w") as f: f.write(csv_content) print("Original CSV content:") print(csv_content) # Use csvlook to pretty-print (run as a subprocess) print("\n--- Output from csvlook ---") try: result = subprocess.run(['csvlook', file_path], capture_output=True, text=True, check=True) print(result.stdout) except subprocess.CalledProcessError as e: print(f"Error running csvlook: {e.stderr}") # Use csvsql to query data (run as a subprocess) print("\n--- Output from csvsql (names of people over 25) ---") try: result = subprocess.run( ['csvsql', '--query', 'SELECT name FROM example WHERE age > 25', file_path], capture_output=True, text=True, check=True ) print(result.stdout) except subprocess.CalledProcessError as e: print(f"Error running csvsql: {e.stderr}") # Clean up the dummy file os.remove(file_path) print(f"\nCleaned up {file_path}")

csvkit --version

Debug

Known issues

breakingVersion 2.0.0 of csvkit dropped support for Python 2, making it a Python 3-only library. Running on Python 2 will result in `ImportError` or other runtime errors.

fix

Ensure your environment uses Python 3.6+ (csvkit 2.2.0 requires Python 3.6+).

affects: 2.0.0 and later

gotchaCSV encoding is a frequent source of issues. `csvkit` defaults to UTF-8, but many CSVs use other encodings (e.g., Latin-1, cp1252).

fix

Specify the correct encoding using the `-e` or `--encoding` flag, e.g., `csvlook -e latin1 input.csv`.

affects: All versions

gotcha`csvkit` tools can consume significant memory when processing very large CSV files, as they often load the entire dataset into memory.

fix

For extremely large files (gigabytes), consider streaming tools or breaking files into smaller chunks. While `csvkit` is powerful, for very large datasets, dedicated big-data tools might be more suitable.

affects: All versions

gotchaAutomatic header detection can sometimes fail on malformed or unusual CSVs, leading to data rows being interpreted as headers or vice versa. This is especially true for files without explicit headers.

fix

Use the `--no-header-row` flag if your CSV lacks a header, or inspect the output carefully. For complex cases, pre-process the CSV to ensure a clean header.

affects: All versions

Errors

Common errors & fixes

csvcut: command not found

The `csvkit` command-line tools are not found in your system's PATH environment variable, or `csvkit` was not installed correctly.

fix

Ensure the directory where pip installs scripts (e.g., `~/.local/bin` on Linux/macOS or `%APPDATA%\Python\Scripts` on Windows) is added to your system's PATH. Alternatively, if using a virtual environment, ensure it is activated.

UnicodeEncodeError: 'ascii' codec can't encode character '\u0105' in position X: ordinal not in range(128)

Python's default ASCII encoding cannot handle non-ASCII characters present in the CSV data when writing output, or `csvkit` cannot decode input when its assumed encoding (often UTF-8 by default) doesn't match the actual file encoding, especially when piping data.

fix

Specify the correct encoding for the input file using the `-e` flag (e.g., `csvcut -e utf8 input.csv`). When piping data, set the `PYTHONIOENCODING` environment variable (e.g., `export PYTHONIOENCODING=utf8; cat input.csv | csvcut`).

csvcut: error: unrecognized arguments: "Column Name"

Column names containing spaces are not properly quoted, causing the shell to split them into multiple arguments that `csvcut` (or other tools) doesn't recognize.

fix

Enclose column names with spaces in single quotes when providing them to options like `-c` (e.g., `csvcut -c 'Column Name With Spaces' myfile.csv`).

Row 2 has 4 values, but Table only has 3 columns.

The CSV file is malformed, meaning a data row has a different number of fields than the header row or other rows, often due to incorrect delimiters, unquoted newlines, or failed CSV dialect sniffing.

fix

Use `csvclean` to identify and fix malformed rows (e.g., `csvclean -a yourfile.csv` to report errors, or `csvclean --join-short-rows --fill-short-rows yourfile.csv > cleaned.csv` to attempt fixes). If dialect sniffing is the issue, explicitly specify `--snifflimit 0 --delimiter ',' --quotechar '"'` with the `csvkit` tool.

_csv.Error: field larger than field limit (131072)

A single field within the CSV file exceeds Python's default maximum field size limit of 131,072 characters.

fix

Increase the maximum field size limit using the `-z` or `--maxfieldsize` option with a larger integer value (e.g., `csvcut -z 1000000 myfile.csv`).

Upgrade

Version history

2.2.0latest on PyPI · released Dec 15, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wireservice/csvkit ↗

packagehttps://pypi.org/project/csvkit/ ↗

docshttps://csvkit.readthedocs.io/en/latest/ ↗