Camelot: Pulling Real Tables Out of PDFs Without Losing Your Mind

You've got a PDF full of tables—financial reports, government data, that one research paper with the perfect dataset—and you need it in a DataFrame. Copy-pasting cell by cell is a special kind of punishment. Camelot is a Python library built specifically to solve this, and it's been quietly doing the job for years.

What It Does

Camelot extracts tables from PDFs and hands them back to you as pandas DataFrames. That's the core promise, and it's exactly what you get. You point it at a file, it returns a TableList object, and each table inside that list carries a .df property you can work with immediately.

Under the hood, it offers five different parsers, which it calls flavors. The lattice parser handles ruled tables—the ones with visible grid lines. The stream parser goes after whitespace-separated tables, where columns are defined by gaps rather than borders. There's also network and hybrid, which use text alignment, and an optional neural ml backend built on Table Transformer for the genuinely hard borderless cases. If you don't want to think about which one fits, flavor="auto" will pick for you.

The library reads from a file path, a URL, raw bytes, or any binary file-like object, and outputs to CSV, JSON, Excel, HTML, Markdown, or SQLite. There's a CLI too, so camelot lattice file.pdf works right from your terminal. The default backend uses pdfium and ships bundled—no system dependencies to wrangle on install.

Why It's Cool

• The ml and ocr extras solve the cases that usually kill table extraction. Most PDF table tools fall apart on borderless tables or scanned documents with no text layer. Camelot's ml backend (installed via pip install "camelot-py[ml]") recovers structure the heuristic parsers can't, and adding [ocr] lets you read image-only PDFs. That's a meaningful expansion of what "table extraction" even means.

• Combined line detection is a small feature with big practical payoff. Setting engine="combined" unions the PDF's native vector ruled lines with OpenCV detection, so tables with faint or partially-rendered borders still get found. If you've ever had a parser silently miss a table because the lines were too light, you'll appreciate this.

• It tells you how well it did. Every table comes with a parsing_report containing accuracy, whitespace, order, and page. There's also a confidence score per table, and TableList.filter(...) for dropping the noise. This is the difference between a tool you trust and a tool you have to babysit.

• Multi-page tables are handled. stack_contiguous() stitches table continuations across page breaks. Anyone who's dealt with a table that spills onto page two knows why this matters.

• The output is boring in the best way. It's a DataFrame. Export formats are one method call. The API doesn't make you learn anything new to get value out of it.

How to Try It

1. Install it:

pip install camelot-py

1. Run it on a PDF:

>>> import camelot
>>> tables = camelot.read_pdf('foo.pdf')
>>> tables
<TableList n=1>
>>> tables[0].df  # a pandas DataFrame

1. Check the quality and export:

>>> tables[0].parsing_report
{
    'accuracy': 99.02,
    'whitespace': 12.24,
    'order': 1,
    'page': 1
}
>>> tables.export('foo.csv', f='csv', compress=True)

You can swap f='csv' for json, excel, html, markdown, or sqlite. Per-table, the methods are to_csv, to_json, to_excel, to_html, to_markdown, and to_sqlite.

There's an interactive quickstart notebook on Colab if you'd rather poke at it before installing anything, and a sample PDF linked in the README to test against.

For the harder stuff, install the extras you need:

pip install "camelot-py[ml]"
pip install "camelot-py[ocr]"

The repo lives at github.com/camelot-dev/camelot.

Final Thoughts

Camelot isn't trying to be everything to everyone—it's a focused tool that does table extraction and does it with a sensible amount of configurability. The ml and ocr backends make it far more capable than the classic lattice/stream approach alone, though you'll only reach for them when the simpler parsers fail. If your work involves pulling structured data out of PDFs on any kind of regular basis, this belongs in your toolkit. It's mature, the API is small, and the fact that it hands you pandas objects means there's almost no friction between extraction and analysis. Worth a look before you write another regex.

Follow @githubprojects for more developer tools and open source projects.