Install & Compatibility
Where this runs
tested against v2.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
176MB installed
● package 176MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
read_pdf
✓ from tabula import read_pdf
✗ import tabula; tabula.io.read_pdf()
While `tabula.io.read_pdf` works, direct import from `tabula` is the common and documented pattern.
convert_into
✓ from tabula import convert_into
environment_info
✓ from tabula import environment_info
Useful for debugging Java environment issues.
This quickstart demonstrates how to extract tables from a remote PDF file into a list of pandas DataFrames using `tabula.read_pdf()`. It also shows how to directly convert PDF tables to a CSV file using `tabula.convert_into()`. Error handling for the common `JavaNotFoundError` is included, as a Java Runtime Environment is a prerequisite.
import tabula
import pandas as pd # often used with tabula-py results
# Example PDF URL with tables
pdf_url = "https://github.com/tabulapdf/tabula-java/raw/master/src/test/resources/technology/tabula/arabic.pdf"
try:
# Read tables from the PDF into a list of DataFrames
# pages='all' extracts from all pages. '1' is default.
# multiple_tables=True is the default from v2.0.0, returning a list even if only one table.
dfs = tabula.read_pdf(pdf_url, pages='all', multiple_tables=True)
if dfs:
print(f"Successfully extracted {len(dfs)} tables.")
for i, df in enumerate(dfs):
print(f"\nTable {i+1}:")
print(df.head()) # Print first few rows of each DataFrame
else:
print("No tables found in the PDF.")
# You can also convert to CSV directly
output_csv_path = "output.csv"
tabula.convert_into(pdf_url, output_csv_path, output_format="csv", pages='all')
print(f"\nTables converted and saved to {output_csv_path}")
except tabula.errors.JavaNotFoundError:
print("Error: Java Runtime Environment (JRE) not found. Please install Java 8+ and ensure it's in your PATH.")
except Exception as e:
print(f"An error occurred: {e}")
tabula --version
Debug
Known issues
breakingtabula-py is a wrapper for tabula-java and requires a Java Runtime Environment (JRE 8+) to be installed on your system and accessible in your system's PATH. Without it, `tabula-py` functions will raise a `tabula.errors.JavaNotFoundError`.fixInstall a Java Runtime Environment (JRE) 8 or newer and ensure its `bin` directory is added to your system's PATH environment variable. You can verify Java availability using `tabula.environment_info()`.
affects: All versions
breakingPython version compatibility has changed across recent releases. Version 2.10.0 dropped support for Python 3.8 and added support for Python 3.13. Version 2.9.0 introduced support for Python 3.12, making `jpype` optional due to its lack of 3.12 support at the time.fixIf using Python 3.8, restrict `tabula-py` to `<2.10.0`. For Python 3.12 or 3.13, install `tabula-py` without the `[jpype]` extra if `jpype` does not yet support your specific Python version (e.g., `pip install tabula-py`). Monitor `jpype`'s compatibility for optimal performance with `[jpype]` extra.
affects: >=2.9.0 (Python 3.12+ users), >=2.10.0 (Python 3.8 users)
gotchaSince v2.9.0, JPype1 is an optional dependency. While `tabula-py` can function without it by falling back to subprocess mode, installing with `pip install tabula-py[jpype]` is recommended for significantly faster execution on compatible Python versions (up to 3.11, and newer once JPype1 adds support).fixFor performance-critical applications, install `tabula-py` with `pip install tabula-py[jpype]`. If you encounter `jpype` related issues, you can explicitly force subprocess mode by passing `force_subprocess=True` to `read_pdf()` and related functions.
affects: >=2.9.0
gotchaInstalling a separate Python package named `tabula` (instead of `tabula-py`) can lead to a namespace conflict, causing `AttributeError: module 'tabula' has no attribute 'read_pdf'` when trying to use `tabula-py` functions.fixEnsure you have `tabula-py` installed and not a conflicting `tabula` package. If a conflict exists, `pip uninstall tabula` before `pip install tabula-py`. `tabula-py`'s functions are typically accessed directly from the `tabula` submodule (e.g., `from tabula import read_pdf`).
affects: All versions
gotchatabula-py (and its underlying tabula-java) cannot extract tables from image-based PDFs; the PDF must contain text-based table information. Additionally, by default, `read_pdf()` only extracts from page 1, and prior to v2.0.0, `multiple_tables` was `False` by default.fixVerify that your PDF contains selectable text, not just images. For multi-page PDFs, always specify `pages='all'` or a list of desired page numbers (e.g., `pages=[1, 2, 5]`). Be aware that `read_pdf()` returns a list of DataFrames (or dicts for JSON output) when `multiple_tables=True` (default since v2.0.0). For complex PDFs, use the `area`, `stream`, or `lattice` options for more precise extraction, and consider trying the Tabula App (GUI tool) to debug extraction logic.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tabula'
This error occurs when the 'tabula' module is not installed or the installation is incomplete.
fixEnsure that 'tabula-py' is installed by running 'pip install tabula-py'.
ImportError: cannot import name 'read_pdf' from 'tabula' (unknown location)
This error occurs when there's a conflict between the 'tabula' and 'tabula-py' packages, leading to import issues.
fixUninstall the 'tabula' package and install 'tabula-py' by running 'pip uninstall tabula' followed by 'pip install tabula-py'.
WindowsError: [Error 2] The system cannot find the file specified
This error occurs when the Java executable is not found in the system's PATH, which is required by 'tabula-py'.
fixEnsure that Java is installed and its 'bin' directory is added to the system's PATH environment variable.
tabula.errors.JavaNotFoundError
This error occurs when 'tabula-py' cannot locate the Java runtime environment, which is necessary for its operation.
fixInstall Java and verify that the 'java' command is accessible from the command line.
tabula.errors.CSVParseError: Error failed to create DataFrame with different column tables.
This error occurs when 'tabula-py' encounters inconsistencies in the table structure within the PDF, leading to parsing issues.
fixSet the 'multiple_tables' parameter to 'True' or specify the 'names' option in 'pandas_options' to handle varying table structures.
Upgrade
Version history
2.10.0latest on PyPI · released Oct 17, 2024
Audit
Dependencies
pandasrequiredFor outputting extracted tables as DataFrames.
JPype1optionalOptional dependency for faster execution via direct JVM communication.
Java Runtime Environment (JRE) 8+requiredExternal dependency required as tabula-py wraps tabula-java. Must be installed and accessible in system PATH.