Install & Compatibility
Where this runs
tested against v2.0.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.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 11.4s · import 1.564s · 359MB
365MB installed
● package 365MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to read a PDF file, extract tables using Camelot's default settings, inspect the parsing report, convert an extracted table to a pandas DataFrame, and export it to a CSV file. It assumes a 'foo.pdf' file with at least one table exists in the execution directory.
import camelot
import pandas as pd
import os
# NOTE: Replace 'foo.pdf' with the path to your actual PDF file.
# You can create a dummy PDF for testing or use an existing one.
# Example: A simple PDF with a table on page 1.
# Ensure the PDF exists for the example to run
if not os.path.exists('foo.pdf'):
print("Please create a 'foo.pdf' with at least one table for this example.")
# For a truly runnable example, one might generate a PDF using ReportLab or FPDF
# For simplicity here, we assume the user provides foo.pdf
exit()
# Read tables from the PDF (defaults to 'lattice' flavor and first page)
tables = camelot.read_pdf('foo.pdf') #
# Print the number of tables found
print(f"Found {tables.n} tables.\n")
if tables.n > 0:
# Access the first extracted table
first_table = tables[0]
# Print parsing report for insights on accuracy and whitespace
print("Parsing Report for the first table:")
print(first_table.parsing_report) #
# Convert the table to a pandas DataFrame
df = first_table.df #
print("\nExtracted DataFrame (first 5 rows):\n", df.head())
# Export the table to CSV
first_table.to_csv('foo_table.csv', index=False) #
print("\nTable exported to foo_table.csv")
# Alternatively, export all tables to a compressed zip file
tables.export('all_tables.zip', f='csv', compress=True) #
print("All tables exported to all_tables.zip")
else:
print("No tables found in 'foo.pdf'. You may need to adjust parameters like 'flavor' or 'pages'.")
camelot --version
Debug
Known issues
gotchaCamelot primarily works with text-based PDFs. It cannot reliably extract tables from scanned documents or image-based PDFs where text is not selectable. Always verify if text in your PDF is selectable via a PDF viewer.fixEnsure your PDF is text-based. For image-based PDFs, consider using OCR tools first to convert them to text-based documents before using Camelot.
affects: All versions
breakingInstallation issues with Ghostscript: Prior to v1.0.0, Ghostscript was a mandatory external dependency, often leading to installation complexities due to system-level setup and PATH configuration, especially on Windows and macOS. While v1.0.0 introduced pypdfium2 as the default Python-installable backend to mitigate this, Ghostscript is still an optional backend and problems can arise if it's explicitly chosen or needed for specific environments.fixFor v1.0.0 and above, use `pip install "camelot-py[base]"` for easier installation. If Ghostscript is required, ensure it's correctly installed on your system and its `bin` directory is added to your system's PATH. Check installation via `from ctypes.util import find_library; find_library("gs")` in Python. affects: <1.0.0 (mandatory), >=1.0.0 (optional backend)
gotchaChoosing the correct parsing 'flavor' is crucial for accurate extraction. 'lattice' (default) is best for tables with clearly defined lines. 'stream' is better for tables where columns and rows are separated by whitespace, not explicit lines. Using the wrong flavor can lead to no tables being found or incorrect data extraction.fixExperiment with both `flavor='lattice'` and `flavor='stream'` when calling `camelot.read_pdf()`. If auto-detection fails, manually specify `table_areas` or `columns` using coordinates obtained via visual debugging.
affects: All versions
gotchaFor PDFs with complex layouts, tables spanning multiple pages, or multiple tables on a single page, Camelot might fail to autodetect all tables or merge unrelated data. The 'stream' flavor, in particular, may treat an entire page as a single table.fixSpecify `pages` to extract from particular pages (e.g., `pages='1,3-5'`). Use `table_areas` to define specific regions where tables are located. For tables spanning multiple pages, extract them individually and then merge using pandas. For multiple tables on one page, defining multiple `table_areas` can help.
affects: All versions
gotchaComplex tables with merged cells, multi-line text within cells, or inconsistent spacing can lead to data being incorrectly grouped into single rows or having unwanted newline characters.fixAdjust parameters like `row_tol` (row tolerance), `split_text` (to split multiline text), and `strip_text` (to remove unwanted characters like '\n' or spaces). Visual debugging with `table.plot()` can help in identifying and fixing these issues.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'camelot'
This error typically occurs when the incorrect package name `camelot` is installed instead of `camelot-py`, or if Camelot-py is installed but not accessible by the Python environment being used.
fixEnsure you install the correct package: `pip install camelot-py`. If already installed, verify your Python environment path.
AttributeError: module 'camelot' has no attribute 'read_pdf'
This error commonly arises when a different, unrelated `camelot` package is installed instead of `camelot-py`, or when a local Python file is named `camelot.py`, shadowing the actual library.
fixUninstall any conflicting `camelot` packages (`pip uninstall camelot`) and then install the correct one (`pip install camelot-py`). If you have a local file named `camelot.py`, rename it.
OSError: Ghostscript is not installed.
Camelot-py relies on Ghostscript, an external dependency, to render PDF pages into images for processing. This error means Ghostscript is either not installed on your system or its executable is not found in your system's PATH environment variable.
fixInstall Ghostscript from its official website (www.ghostscript.com/releases/gsdnld.html) and add its 'bin' directory to your system's PATH environment variable. A system restart might be required for changes to take effect.
UserWarning: No tables found on page-X
This warning indicates that Camelot could not detect any tables on the specified PDF page using the default parameters (usually 'lattice' flavor). This often happens with PDFs where tables are not clearly defined by lines, or when the `flavor` or `table_regions` parameters are not appropriately set for the PDF's structure.
fixTry using the 'stream' flavor (`camelot.read_pdf('file.pdf', flavor='stream')`). If still no tables are found, you may need to manually define table areas using the `table_regions` parameter or adjust other parsing options like `columns` or `row_tol`. ImportError: cannot import name 'TableList' from 'camelot.core'
This error usually stems from an incomplete or corrupted installation of `camelot-py`, often due to conflicts with an older or different `camelot` package.
fixPerform a clean reinstallation by first uninstalling both `camelot` and `camelot-py` (`pip uninstall camelot` then `pip uninstall camelot-py`), then reinstall `camelot-py` with necessary extras, e.g., `pip install camelot-py[cv]` or `pip install camelot-py[all]`. Restarting your Python kernel or environment might also be necessary.
Upgrade
Version history
2.0.0latest on PyPI · released Jun 4, 2026
Audit
Dependencies
pypdfium2requiredDefault image conversion backend since v1.0.0, required for core functionality. Automatically installed with `camelot-py[base]`.
GhostscriptoptionalOptional image conversion backend; required for the 'lattice' flavor in older Camelot versions (<1.0.0) or if explicitly chosen as the backend. Often requires manual system-level installation and PATH configuration.
opencv-python-headlessoptionalRequired for the `[cv]` extra, which enables some image processing capabilities in table detection.
matplotliboptionalRequired for visual debugging features (e.g., `table.plot()`).