Install & Compatibility
Where this runs
tested against v3.10.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
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.034s · 18.2MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 6.4s · import 0.030s · 19MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Dataset
✓ from tablib import Dataset
Databook
✓ from tablib import Databook
Used for handling multiple Dataset objects, typically for multi-sheet Excel files.
This quickstart demonstrates how to create a `Dataset` object, add headers, append rows, add a new column, and then export the data to different formats like CSV and JSON. It also includes a commented-out example for exporting to an XLSX file.
import tablib
# Create a new Dataset
data = tablib.Dataset()
# Add headers
data.headers = ['First Name', 'Last Name', 'Age']
# Add rows
data.append(['Kenneth', 'Reitz', 22])
data.append(['Bessie', 'Monke', 20])
# Add a new column with data
data.append_col([True, False], header='Is Student')
print("CSV Export:")
print(data.export('csv'))
print("\nJSON Export:")
print(data.export('json'))
# Example of saving to a file (uncomment to run)
# with open('output.xlsx', 'wb') as f:
# f.write(data.export('xlsx'))
# print("\nData exported to output.xlsx")
Debug
Known issues
breakingThe logic for `Row.lpush` and `Row.rpush` methods was reversed in Tablib 2.0.0. In versions 1.x, `lpush` appended and `rpush` prepended, which was non-standard. This was corrected in 2.0.0.fixReview code using `lpush` or `rpush` on `Row` objects when upgrading to 2.0.0+ to ensure the intended prepend/append behavior.
affects: 1.x -> 2.0.0
breakingPython 2 support was dropped with Tablib 1.0.0. Python 3.5 support was dropped with Tablib 3.0.0.fixEnsure your project uses Python 3.6+ for Tablib 3.x.
affects: <1.0.0 for Python 2, <3.0.0 for Python 3.5
breakingStarting with Tablib 1.0.0, all format dependencies became optional. Previously, they might have been installed by default. To install all possible format dependencies, you now need to use `pip install "tablib[all]"`.fixIf upgrading from pre-1.0.0 and encountering `ImportError` for format-specific modules, use `pip install "tablib[all]"` or install specific format dependencies like `pip install "tablib[xlsx]"`.
affects: <1.0.0 -> 1.0.0+
gotchaWhen exporting CSV files on Windows, if you don't specify `newline=''` when opening the file in write mode, Excel might display a blank line between each row.fixAlways open CSV files with `newline=''` when exporting Tablib's CSV output to a file: `with open('output.csv', 'w', newline='') as f: f.write(data.export('csv'))`. affects: All versions (Python's `csv` module behavior)
gotchaThe legacy XLS format (Excel 97-2003) has a limitation of 65,000 rows. If you are dealing with larger datasets, you should use the XLSX format instead.fixFor datasets exceeding 65,000 rows, export to XLSX (`data.export('xlsx')`) rather than XLS (`data.export('xls')`). affects: All versions when using XLS
gotchaWhen importing XLSX or ODS files with `read_only=True` (which is the default for XLSX), Tablib relies on the spreadsheet declaring correct dimensions. Some programs might generate files with incorrect dimensions, leading to incomplete reads.fixIf encountering issues with large XLSX/ODS files not importing fully, consider checking the spreadsheet source or, if possible, disable `read_only` (though this might increase memory usage for large files).
affects: All versions with lazy reading
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tablib'
The tablib library has not been installed in the current Python environment.
AttributeError: 'Dataset' object has no attribute 'json'
Users incorrectly attempt to access export formats (like 'json', 'csv', 'xlsx') as direct attributes or methods of a Dataset object, instead of using the export() method with the format string.
fixmy_dataset.export('json') ImportError: You need to install 'openpyxl' to import/export .xlsx files.
The user is attempting to import or export data in a specific format (e.g., XLSX) that requires an optional dependency which has not been installed.
fixpip install openpyxl (or the specific dependency mentioned in the error for the desired format, e.g., `pip install xlwt` for XLS, `pip install pandas` for DataFrames).
TypeError: 'int' object is not iterable
This error often occurs when attempting to append a single, non-iterable item (like an integer or a string) as a row to a Dataset, but Dataset methods like append() or add_row() expect an iterable (list or tuple) representing the row's values.
fixEnsure that data appended to the Dataset is provided as an iterable, such as `my_dataset.append(['value1', 'value2'])` or `my_dataset.append(('value1', 'value2'))`. Upgrade
Version history
3.10.0latest on PyPI · released Jul 31, 2026
Audit
Dependencies
odfpyoptionalFor OpenDocument Spreadsheet (ODS) format support.
openpyxloptionalFor Excel 07+ Spreadsheet (XLSX) format support.
pandasoptionalFor Pandas DataFrame export/import support.
pyyamloptionalFor YAML format support.
tabulateoptionalFor CLI table format export support.
xlrdoptionalFor Legacy Excel Spreadsheet (XLS) import support.
xlwtoptionalFor Legacy Excel Spreadsheet (XLS) export support.