agate-excel is an extension for the `agate` data analysis library, providing read support for both older XLS and newer XLSX Excel file formats. The current version is 0.4.2, released on December 15, 2025, and it appears to be actively maintained, supporting recent Python versions including 3.13 and 3.14. It integrates seamlessly with `agate` by adding file reading methods directly to `agate.Table` instances.
Install & Compatibility
Where this runs
tested against v0.4.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.920 runs
installs and imports cleanly · install 0.0s · import 0.445s · 57.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.9s · import 0.404s · 58MB
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
agateexcel
✓ import agate
import agateexcel
✗ from agateexcel import Table
agate-excel monkey-patches `agate.Table` directly; its functionality is accessed via `agate.Table.from_xls()` or `agate.Table.from_xlsx()` after importing both `agate` and `agateexcel`.
This quickstart demonstrates how to read data from an XLSX file using `agate-excel`. It first creates a simple XLSX file using `openpyxl` (if available) and then loads it into an `agate.Table` object. The methods `from_xls()` and `from_xlsx()` are added directly to `agate.Table` after `import agateexcel`.
import agate
import agateexcel
import os
# Create a dummy Excel file for demonstration
# In a real scenario, 'example.xlsx' would already exist.
# Using openpyxl to create a simple .xlsx file
try:
from openpyxl import Workbook
wb = Workbook()
ws = wb.active
ws['A1'] = 'Header1'
ws['B1'] = 'Header2'
ws['A2'] = 1
ws['B2'] = 'Value1'
ws['A3'] = 2
ws['B3'] = 'Value2'
xlsx_path = 'example.xlsx'
wb.save(xlsx_path)
print(f"Created temporary Excel file: {xlsx_path}")
# Load an XLSX file
table_xlsx = agate.Table.from_xlsx(xlsx_path)
print("\nData from XLSX:")
table_xlsx.print_table()
# You can also specify a sheet by name or index
# table_xlsx_sheet2 = agate.Table.from_xlsx(xlsx_path, sheet=0)
# Clean up the dummy file
os.remove(xlsx_path)
print(f"Removed temporary Excel file: {xlsx_path}")
except ImportError:
print("openpyxl not installed. Cannot create dummy .xlsx file.")
print("Please install openpyxl (pip install openpyxl) to run the full quickstart example.")
except Exception as e:
print(f"An error occurred: {e}")
# Note: Reading .xls files requires xlrd, which is not used in this dummy file creation.
# Example for XLS (assuming 'example.xls' exists):
# table_xls = agate.Table.from_xls('example.xls')
Debug
Known issues
breakingThe default behavior of the `reset_dimensions` argument in `Table.from_xlsx()` changed in version 0.4.0 from `False` to `None`. If `reset_dimensions` is `None` and the worksheet's dimensions are reported as `A1:A1` in the file, `agate-excel` will now recalculate the actual dimensions. This can alter how tables with incorrectly reported dimensions are parsed.fixTo revert to the previous behavior of never recalculating dimensions, explicitly set `reset_dimensions=False` when calling `agate.Table.from_xlsx()`.
affects: 0.4.0 and later
gotchaagate-excel extends `agate.Table` using a monkey-patching pattern. This means that simply importing `agateexcel` globally modifies the behavior of all `agate.Table` instances within your application. Be aware of this global modification, especially in larger projects or when managing dependencies carefully.fixNo direct fix, but be mindful of the side effects of importing `agateexcel`. Ensure it's imported in a scope where this global modification is acceptable.
affects: All versions
gotchaPython version compatibility can change between major releases. For instance, version 0.3.0 dropped support for Python 3.5, 3.6, and 3.7. The latest version 0.4.2 explicitly adds support for Python 3.13 and 3.14.fixAlways check the official documentation or changelog for the specific version of `agate-excel` you are using to ensure compatibility with your Python environment. Upgrade `agate-excel` and its dependencies (like `openpyxl` and `xlrd`) together.
affects: All versions (check changelog for specific changes)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'agate.excel'
The 'agate-excel' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install agate-excel'.
ImportError: No module named 'xlrd'
The 'xlrd' package, required for reading older Excel files, is not installed.
fixInstall the package using pip: 'pip install xlrd'.
AttributeError: module 'agate.Table' has no attribute 'from_xls'
The 'agate-excel' extension is not imported, so the 'from_xls' method is unavailable.
fixImport the extension in your script: 'import agateexcel'.
ValueError: Sheet index 1 is out of range
The specified sheet index does not exist in the Excel file.
fixVerify the sheet index or name, ensuring it exists in the file.
TypeError: 'NoneType' object is not callable
Attempting to call a method on a 'None' object, possibly due to a failed file read operation.
fixEnsure the Excel file path is correct and the file is accessible.
Audit
Dependencies
agaterequiredCore data analysis library that agate-excel extends.
openpyxlrequiredRequired for reading .xlsx files.
xlrdrequiredRequired for reading .xls files.
olefilerequiredA dependency often used by xlrd for parsing OLE2 files (.xls).