Install & Compatibility
Where this runs
tested against v1.7.24 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.252s · 20.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.232s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
petl
✓ import petl as etl
The convention is to import petl with the alias `etl` for brevity and clarity in ETL operations.
This quickstart demonstrates a basic ETL pipeline using petl: extracting data from a CSV, filtering rows based on conditions, adding a new field, and loading the result into another CSV file. petl tables are lazy, meaning operations are defined but not executed until data is requested (e.g., when writing to a file or viewing with `look()`).
import petl as etl
import os
# Simulate an input CSV file
csv_data = """name,age,city
alice,30,new york
bob,24,london
charlie,35,paris
diana,28,london
"""
with open('input.csv', 'w') as f:
f.write(csv_data)
# Extract: Read data from a CSV file
table1 = etl.fromcsv('input.csv')
# Transform: Filter rows where age is > 25 and city is 'london'
table2 = etl.select(table1, lambda row: row.age > 25 and row.city == 'london')
# Add a new column 'status'
table3 = etl.addfield(table2, 'status', 'eligible')
# Load: Write the transformed data to a new CSV file
etl.tocsv(table3, 'output.csv')
# Verify the output
with open('output.csv', 'r') as f:
print(f.read())
# Expected output:
# name,age,city,status
# bob,24,london,eligible - Correction: This should be: bob,24,london,eligible (if age > 20 for example)
# Corrected expected output (age > 25 AND city == 'london'):
# name,age,city,status
# diana,28,london,eligible
Debug
Known issues
breakingVersion 2.0 of petl will drop support for Python 2.7, with the minimum supported Python version becoming 3.6. Code running on older Python environments will require an upgrade.fixEnsure your Python environment is 3.6 or newer before upgrading to petl 2.0. Update any Python 2.7 specific syntax.
affects: All versions prior to 2.0.x when migrating to Python 3.6+
gotchaWhen creating custom generator functions within a petl pipeline, directly raising `StopIteration` to signal exhaustion will result in a `RuntimeError` in Python 3.7 and later, due to PEP 479. petl itself has addressed this internally in `v1.7.8` and `v1.7.14`.fixReplace explicit `raise StopIteration` with a simple `return` statement in your custom generator functions. Alternatively, catch `StopIteration` if using `next()` calls within your generator.
affects: Python 3.7+ (not petl-specific, but applies to user-defined generators)
gotchaWhile petl emphasizes lazy evaluation, certain operations like `sort()`, `tojson()` (without `lines=True`), `look()`, or `see()` can load entire tables into memory, potentially leading to high memory consumption for very large datasets.fixBe mindful of operations that require materializing the entire table. For large datasets, consider chunking, using `lines=True` for JSON output, or exploring `petlx` extensions or alternative packages (e.g., Dask, PyTables) for memory-intensive tasks if petl's built-in options are insufficient.
affects: All versions
gotchaPrior to `v1.7.16`, joining tables with uneven rows could produce incorrect results. Users performing join operations on such tables with older versions might experience data integrity issues.fixUpgrade to petl `v1.7.16` or newer to benefit from the fix for joining tables with uneven rows.
affects: <1.7.16
gotchaWhen using `etl.fromdicts()` without explicitly providing a header, the order of fields inferred from sampling the input dictionaries might not be stable or consistent across runs.fixAlways provide an explicit header argument to `etl.fromdicts()` for predictable column ordering, e.g., `etl.fromdicts(dicts, header=['field1', 'field2'])`. Alternatively, use `etl.sortheader()` on the resulting table.
affects: All versions
gotchaIn `v1.7.12`, a fix clarified that `to*()` functions (e.g., `tocsv()`, `tojson()`) should output to `stdout` by default if no specific output file/source is provided. Code on older versions or code expecting a different default behavior might need adjustment.fixExplicitly specify an output file for `to*()` functions (e.g., `etl.tocsv(table, 'output.csv')`) to avoid unintended output to `stdout`.
affects: <1.7.12
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'petl'
The `petl` package is not installed in the Python environment being used, or the Python interpreter cannot find it in its search path.
fixInstall the `petl` package using pip: `pip install petl`
AttributeError: module 'string' has no attribute 'maketrans'
This error typically occurs when an older version of `petl` (or code relying on Python 2 string functions) is run with Python 3, where `string.maketrans` was moved to `str.maketrans` or removed.
fixUpgrade `petl` to the latest version (`pip install --upgrade petl`) to ensure Python 3 compatibility, or explicitly use `str.maketrans` if you are writing custom string manipulation.
AttributeError: module 'petl' has no attribute 'some_function' (e.g., 'fromcolumns')
This indicates that a specific function or method being called, such as `fromcolumns`, does not exist in the installed version of `petl`. This often happens when following tutorials or examples written for a newer version of the library while an older version is installed.
fixUpgrade `petl` to its latest version to access recently added or renamed functions: `pip install --upgrade petl`
TypeError: load_workbook() got an unexpected keyword argument 'use_iterators'
This error arises when `petl`'s XLSX reading functions attempt to use an argument (`use_iterators`) that has been removed or changed in newer versions of its `openpyxl` dependency.
fixUpgrade `petl` to a version compatible with your `openpyxl` version, or, if `petl` is already up-to-date, consider downgrading `openpyxl` if that's an option for your project: `pip install --upgrade petl` or `pip install openpyxl==<compatible_version>` (e.g., `openpyxl==2.3.5` might be needed for very old petl versions, but generally upgrading petl is the best fix).
Upgrade
Version history
1.7.24latest on PyPI · released Aug 19, 2026
Audit
Dependencies
petlxoptionalCompanion package for domain-specific and experimental extensions.
SQLAlchemyoptionalFor interacting with relational databases.
openpyxloptionalFor reading and writing .xlsx Excel files.
xlrdoptionalFor reading .xls Excel files (legacy format).
xlwtoptionalFor writing .xls Excel files (legacy format).
fsspecoptionalFor reading and writing from remote and cloud filesystems.
pandasoptionalFor interoperability with pandas DataFrames.
numpyoptionalFor interoperability with NumPy arrays.