Install & Compatibility
Where this runs
tested against v1.14.2 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.467s · 53.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.4s · import 0.404s · 54MB
51MB installed
● package 51MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Table
✓ import agate
table = agate.Table(...)
✗ from agate import Table # Often fine, but import agate is canonical for top-level access
While `from agate import Table` works, the documentation commonly shows `agate.Table` after `import agate` to keep the namespace clean and explicit.
TypeTester
✓ from agate import TypeTester
Sum
✓ from agate.aggregations import Sum
This quickstart demonstrates loading data from a CSV (simulated in-memory), filtering rows, grouping data, aggregating results (mean and sum), and ordering the final table. It highlights `agate`'s immutable operations, where methods like `where()` and `group_by()` return new table objects.
import agate
import csv
import io
# Create a dummy CSV in memory for a runnable example
csv_data = """name,age,city,salary
Alice,30,New York,70000
Bob,24,London,50000
Charlie,30,New York,75000
David,35,London,90000
Eve,24,Paris,60000
"""
# Use io.StringIO to simulate a file for from_csv
with io.StringIO(csv_data) as f:
# agate automatically infers types with TypeTester by default
table = agate.Table.from_csv(f)
print("Original Table:")
table.print_table()
# Filter rows where age is less than 30
filtered_table = table.where(lambda row: row['age'] < 30)
print("\nFiltered Table (age < 30):")
filtered_table.print_table()
# Group by city and calculate average salary
from agate.aggregations import Sum, Mean
by_city = table.group_by('city')
averages = by_city.aggregate([
('average_salary', Mean('salary')),
('total_employees', Sum('age', cast=True)) # Using Sum on age as a proxy for count
])
print("\nAggregated by City (Average Salary & Total Employees):")
averages.print_table()
# Order by average salary, descending
ordered_averages = averages.order_by('average_salary', reverse=True)
print("\nOrdered by Average Salary (Descending):")
ordered_averages.print_table()
Debug
Known issues
breakingAgate has dropped official support for Python 2.x. Users must ensure they are running Python 3.5 or newer. PyPI listings indicate active testing and support for Python 3.10-3.14.fixUpgrade your Python environment to Python 3.5+ (preferably a recent stable version like 3.9+). If migrating from very old projects, update `agate` accordingly.
affects: <1.0 (for full removal), 1.0+ (requires Python 3)
gotchaAgate's core design principle dictates that `Table` objects are immutable. Operations like `select()`, `where()`, or `order_by()` do not modify the original table in-place; instead, they return *new* `Table` instances.fixAlways assign the result of table operations to a new variable (e.g., `new_table = original_table.where(...)`) or chain operations (e.g., `table.where(...).order_by(...)`).
affects: All versions
gotchaWhen loading data from sources like CSV, `agate` uses a `TypeTester` to automatically infer column data types. While generally effective, it can sometimes guess incorrectly, especially with ambiguous data.fixIf type inference is wrong, manually specify column types when loading data using the `column_types` argument in `Table.from_csv` or by instantiating `TypeTester` with `force` overrides. Example: `tester = agate.TypeTester(force={'my_column': agate.Text()}); table = agate.Table.from_csv(..., column_types=tester)`. affects: All versions
gotchaThere are multiple Python libraries with 'Agate' in their name. This entry refers to `wireservice/agate`, a data analysis library (`pip install agate`). Another common one is `obiba-agate`, which is a client for an 'Agate server' and has different use cases and dependencies.fixAlways verify the correct library by its PyPI slug (`agate`) and maintainer (`wireservice`) to ensure you are installing the intended data analysis library. Check documentation links (e.g., `agate.rtfd.org`) to confirm.
affects: All versions
breakingThe `agate.aggregations.Sum` aggregate function does not accept a `cast` keyword argument. Attempting to pass `cast=True` (or any value) to its constructor will result in a `TypeError`. This applies to most `agate` aggregate functions; type conversion should generally be handled before aggregation.fixRemove the `cast` argument from the `agate.aggregations.Sum` constructor. Ensure the column being aggregated is already of the appropriate numeric type for summation. If type conversion is necessary, apply it to the column using `table.compute()` or similar methods *before* performing the aggregation.
affects: All versions
gotchaThe `agate.aggregations.Sum` class does not accept a `cast` keyword argument during initialization. Passing `cast` to `Sum()` will result in a `TypeError`.fixRemove the `cast` argument when initializing `agate.aggregations.Sum`. Ensure the column being aggregated is already of a numeric type. If explicit casting is required, perform it in a separate `Table.compute()` operation before applying the aggregation.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'agate'
This error occurs when the 'agate' library is not installed in your Python environment.
fixInstall the 'agate' library using pip: 'pip install agate'.
ImportError: cannot import name 'Table' from 'agate'
This error occurs when attempting to import 'Table' from 'agate' without the library being installed or due to an incorrect import statement.
fixEnsure 'agate' is installed and use the correct import statement: 'from agate import Table'.
AttributeError: module 'agate' has no attribute 'Table'
This error occurs when the 'agate' module is not properly installed or there is a naming conflict with another module.
fixVerify that 'agate' is installed correctly and that there are no conflicting module names in your project.
agate.exceptions.CastError: Can not parse value '200.000.000' as Decimal.
This error occurs when 'agate' encounters a value formatted with periods as thousand separators, which it cannot parse as a decimal number.
fixEnsure that numerical values are formatted correctly, using commas as thousand separators or removing them entirely before processing with 'agate'.
ImportError: cannot import name 'isawaitable' from 'inspect'
This error occurs when attempting to import 'isawaitable' from the 'inspect' module in a Python version that does not support it.
fixEnsure you are using a Python version that includes 'isawaitable' in the 'inspect' module, or update your Python interpreter to a compatible version.
Upgrade
Version history
1.14.2latest on PyPI · released Feb 27, 2026
Audit
Dependencies
BabelrequiredInternationalization and localization utilities.
isodaterequiredISO 8601 date/time/duration parser and formatter.
leatherrequiredPure-Python charting library used for generating simple charts.
parsedatetimerequiredNatural language date/time parser.
python-slugifyrequiredGenerates clean, URL-safe slugs.
pytimeparserequiredTime expression parser.
tzdatarequiredIANA time zone database for Python.
PyICUoptionalFor non-English locale support, installed via `agate[icu]`.