Tabulator

1.53.5 · active · verified Fri Apr 17

Tabulator provides a consistent interface for reading and writing tabular data from various sources (e.g., CSV, Excel, JSON, Google Sheets) in a streaming fashion. It aims to simplify data integration by abstracting away the underlying file formats. The current version is 1.53.5, and it maintains a regular release cadence with minor updates and bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'tabulator'
```
cause The tabulator library is not installed in your current Python environment.

fix Install the library: `pip install tabulator`
```
ModuleNotFoundError: No module named 'openpyxl'
```
cause You are trying to read an XLSX (Excel) file, but the `openpyxl` dependency is not installed.

fix Install the required extra: `pip install tabulator[xlsx]`
```
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x__ in position __: invalid start byte
```
cause Your CSV file is not encoded in UTF-8, but tabulator is trying to decode it as such by default.

fix Specify the correct encoding for your file, e.g., `Stream('data.csv', encoding='latin-1')` or `encoding='cp1252'`.
```
FileNotFoundError: [Errno 2] No such file or directory: 'your_file.csv'
```
cause The specified file path is incorrect or the file does not exist at that location.

fix Verify the file path is absolute or relative to your script's working directory. Ensure the file actually exists.

Warnings

breaking Tabulator v1.0.0 introduced a major API refactor. The 'Table' class was removed and replaced entirely by the 'Stream' class. Older code using 'Table' will no longer work.
Fix: Migrate your code to use `from tabulator import Stream` and adapt to its API. All options are now passed to the `Stream` constructor.
gotcha Reading certain file formats (e.g., Excel, JSON Lines, remote files) requires installing optional dependencies. Without them, you will encounter `ModuleNotFoundError`.
Fix: Install the necessary extra dependencies, e.g., `pip install tabulator[xlsx]`, `pip install tabulator[xls]`, `pip install tabulator[jsonl]`, or `pip install tabulator[http]` for remote files. For all common extras, use `pip install tabulator[xlsx,xls,jsonl,http]`.
gotcha CSV files often have encoding issues. If you encounter `UnicodeDecodeError`, it's likely due to an incorrect character encoding.
Fix: Explicitly specify the encoding when creating the Stream, e.g., `Stream('data.csv', encoding='latin-1')`. Common encodings include 'utf-8', 'latin-1', 'cp1252'.

Install

pip install tabulator Base installation
pip install tabulator[xlsx,xls,jsonl,http] With all common optional dependencies

Imports

Stream
wrong:
```
from tabulator import Table
```
correct:
```
from tabulator import Stream
```
The 'Table' class was removed in Tabulator v1.0.0 as part of a major API refactor; 'Stream' is the current and recommended class for data processing.

Quickstart

This quickstart demonstrates how to use `tabulator.Stream` to read tabular data from a remote CSV file. It iterates through the rows, printing the headers and the first few data rows. The Stream object handles opening and closing the data source automatically.

import os
from tabulator import Stream

# Example: Read a CSV file from a URL
csv_url = "https://raw.githubusercontent.com/frictionlessdata/tabulator-py/master/data/table.csv"

# Ensure the URL is accessible or provide a local path
try:
    with Stream(csv_url) as stream:
        print(f"Headers: {stream.headers}")
        print("First 5 rows:")
        for i, row in enumerate(stream):
            if i >= 5:
                break
            print(row)
except Exception as e:
    print(f"Could not read data from {csv_url}: {e}")

# Example: Reading a local CSV file (ensure 'example.csv' exists)
# You can create a dummy file for local testing:
# with open('example.csv', 'w') as f:
#     f.write('id,name\n1,Alice\n2,Bob')
#
# local_csv_path = 'example.csv'
# if os.path.exists(local_csv_path):
#     with Stream(local_csv_path) as stream:
#         print(f"\nLocal CSV Headers: {stream.headers}")
#         print(f"Local CSV First row: {next(iter(stream))}")
# else:
#     print(f"\nSkipping local CSV example: {local_csv_path} not found.")

view raw JSON →