Repository navigation
Releases
v2.0.0
[2.0.0] — 2026-06-04
The 2.0 release rolls up a substantial backend migration, the resulting
performance work, an optional neural (Table Transformer) backend for
borderless and scanned tables, and a handful of small but user-visible
breaking changes. Heads-up if upgrading from 1.0.x — see the
migration guide:
Breaking
- Dropped Python 3.9 (EOL October 2025). Minimum supported is now
Python 3.10. (#740) flavor="lattice"defaultline_scalechanged from 40 to 15 to match
the long-standing implementation (the CLI andread_pdfdocstring used
to say 40 but the Lattice parser always defaulted to 15). Tables that
relied on the documented-but-unimplemented40will need
read_pdf(..., line_scale=40)explicitly. (#709)Table.to_excelnow defaults toindex=False, header=Falseto match
Table.to_csv. Excel exports no longer carry the pandas auto-generated
row index / column header by default. Opt back in with
table.to_excel(path, index=True, header=True). (#711)TableListconstructor materialises its iterable input to a list
immediately, sobool()andlen()work onTableList(generator())
inputs. A generator passed in will be exhausted at construction time
rather than at first access. (#710)PDFHandler.pagesis a property (was an attribute). Reads work
unchanged; the value is now resolved lazily on first access. No callers
in the wild set it, but if you subclassed and overrode it as an
attribute, that no longer works. (#732)- PDF backend swapped from
pypdf+pdfminer.sixto
playa-pdf. The dependency
install set is smaller, encrypted-PDF handling is more accurate, and
parser hot paths shed several layers of per-page-temp-PDF dance. Pure
import camelotcallers should see no API change.
Added
- Optional neural
flavor="ml"backend (Table Transformer / TATR). A
neural model supplies the row/column/spanning-cell structure while cell
text is filled from the PDF's own text layer — the model never emits cell
text, so it cannot hallucinate or alter a value. Aimed at borderless tables,
where the heuristic parsers plateau: on the FinTabNet borderless benchmark it
roughly doubles TEDS (~0.20 → ~0.37) overnetwork/hybrid. Heavy
dependencies are optional and imported lazily —pip install "camelot-py[ml]"
— soimport camelotand the other flavors never load PyTorch. The box→grid
post-processing and image→PDF mapping are pure (torch-free) and unit-tested.
(#809) flavor="ml"reads scanned / image-only PDFs via optional OCR. With no
text layer (ocr="auto", the default) — or always withocr=True— cell
text comes from OCR of the rendered page instead of the PDF text layer;
structure still comes from the model. This lifts Camelot's long-standing
"needs a text layer" limitation. Opt in withpip install "camelot-py[ocr]".
Still geometry + recognised text (no invented cells);split_text/
flag_sizearen't supported in OCR mode. (#809)TableList.filter(...)— post-extraction convenience to drop noise /
low-quality tables bymin_rows,min_columns,min_accuracy,
max_whitespace. Returns a newTableList(composable); all thresholds
default to a no-op so nothing is dropped unless asked.engine="combined"forflavor="lattice"(and the lattice half of
flavor="hybrid"): unions the PDF's native vector ruled lines into the
rasterised OpenCV line masks before contour/joint detection, so tables
whose rules render faintly (vector strokes, anti-aliasing) are still
found. Safe by construction — raster always runs, vector lines can only
add, so output is never worse thanengine="raster". It is now the
default lattice engine and vector lines are clipped to
table_regions. (#763)engine="vector"forflavor="lattice": detects tables purely from
the PDF's native vector ruled lines, skipping page rasterisation and
OpenCV entirely — the fastest path for PDFs whose tables are drawn
with real vector strokes. (#763)engine="vector"forflavor="hybrid"— the render-free hybrid.
Hybrid's lattice half now also acceptsengine="vector", so the network
text-edge alignment is merged (via the completeness-gated combine) with
ruled lines read straight from the PDF's vector graphics — no page
render, no OpenCV. On the in-repo ICDAR-2013 benchmark it matches or
beatsengine="raster"hybrid on every metric (F1 0.702→0.726, TEDS
0.724→0.755, row 0.417→0.464, col 0.689→0.715) at ~6× less time
(113s→19s); on FinTabNet.c (borderless) it matches raster hybrid's
quality at ~2.4× less time. Hybrid also now drops empty tables the vector
ruled-line set can raise from decorative page borders / form rules (which
in turn liftsengine="raster"hybrid F1 from removing those spurious
detections). (#39)flavor="auto": render the first requested page, count ruled
horizontal/vertical lines, picklatticewhen ruled andnetwork
otherwise. Emits aUserWarningnaming the chosen flavor. (#737)Table.confidence— unified per-table quality score in[0, 1]
computed as(accuracy / 100) * (1 - whitespace / 100). Now appears as
a"confidence"key inTable.parsing_reportalongside the existing
accuracy/whitespace/page/order. Suitable for production
filtering. The wholeparsing_reportschema is now documented in the
property docstring. (#739)per_pageparameter onread_pdf(..., per_page={...})— apply
per-page kwarg overrides (includingflavor) on top of the global
kwargs. Useful for multi-layout PDFs where some pages need different
table_areas/columns/flavorthan the rest. Concept originally
proposed by @sverma25 in #41. (#41)strip_text=now accepts a list/tuple of substrings alongside the
long-standing per-characterstrform.strip_text=["[1]", "[2]"]
strips those footnote markers as whole substrings;
strip_text="[]"keeps the existing per-character behaviour. (#484)replace_textparameter onread_pdf— dict of substring →
replacement applied to every cell's text just before assignment.
Unlikestrip_text(which can only remove),replace_textrewrites
with arbitrary text — useful for collapsing soft-broken words
({" \n": " "}), normalising abbreviations, or rewriting unit
names. Keys are matched as literal substrings; when several keys
could match at the same position the longest one wins. (#482)read_pdfacceptsbytesand binary file-like objects as
filepath, in addition to str/Path and URLs.io.BytesIO, an open
"rb"handle,requestsresponse.raw, etc. all work. The bytes
are spilled to a temp file once (so the Lattice OpenCV image
conversion keeps working) and cleaned up on context-manager exit.
Long-standing requests #170, #245. (#270)cpu_countparameter onread_pdf(..., parallel=True, cpu_count=N)
andPDFHandler.parse(...)— caps the worker count when running in
parallel. Defaults to all cores; clamped to
[1, multiprocessing.cpu_count()]. (#712)camelot-pyCLI alias matching the PyPI package name —
uvx camelot-py …works directly without the--from camelot-py
prefix. (#738)--formatis now optional in the CLI: when omitted, the format is
inferred from the--outputextension (.csv,.xlsx,.html,
.json,.md,.sqlite, etc.). (#738)Table.to_exceldefaults toindex=False, header=False(under
Breaking but worth calling out under Added too — most users will
prefer the new shape).- Python 3.14 stable + 3.15 experimental rows added to the CI matrix.
Wheels for both Pythons install correctly on Linux/macOS/Windows. (#706)
Changed
- Default lattice
engineis now"combined"(was"raster"); the
transientengine="auto"introduced earlier in the 2.0 cycle was removed.
Existingflavor="lattice"calls pick up combined automatically and it is
never worse than raster.enginestays lattice-only and is rejected for the
text-based flavors. (#803) flavor="hybrid"runs its lattice half withengine="combined"too
(was"raster"). With the completeness gating this lifts hybrid on ruled
documents — in-repo ICDAR-2013 TEDS 0.724→0.806, row 0.417→0.659,
col 0.689→0.868. (#807)
Changed (performance)
-
Lattice raster render skips the PNG round-trip (~20-26% faster). The
page was rendered to a PIL image, saved to a PNG, then immediately
cv2.imread-ed back — the encode alone was ~a quarter of the raster
time. The Lattice engine now renders straight to an in-memory BGR array
(ImageConversionBackend.to_array, pdfium-native; other backends fall
back to convert+imread). Output is byte-identical (PNG was lossless).
(#40) -
text_in_bbox≈ 30× faster on busy lattice pages. The original
O(n³) duplicate-discard pass became O(n²) in #718, then the whole
function was NumPy-vectorised in #731 — a 3-4× win on top of #718 on
realistic 50-500-text-line bboxes. Memory-safe fallback at n > 1500. -
get_table_index3-13×. #727 collapsed the row scan + best-overlap
tracking, #733 added a lazy NumPy +bisectrow-band lookup
(O(log rows)) plus per-table caches onTable(_rows_np,
_cols_np,_rows_disjoint). -
read_pdfopens the PDF once per call instead of twice. Page
resolution is deferred until the parse already has theplayahandle
open. Doubles throughput on workloads that loop over many short PDFs.
(#732) -
random_string4× (#718) andcompute_whitespacecleanup (#727) —
small, mostly readability. -
A
bench/directory now ships a couple of standalone microbenchmarks
(bench_get_table_index.py) and a negative-result bench
(bench_negative_results.py) documenting cases where NumPy did not
...
v2.0.0rc1
First release candidate for Camelot 2.0 — please test and report issues before the final 2.0.0.
Highlights
- New PDF backend —
pypdf+pdfminer.six→playa-pdf: smaller install, accurate encrypted-PDF handling, faster hot paths. - Optional neural
flavor="ml"(Table Transformer) for borderless tables, with optional OCR for scanned / image-only PDFs —pip install "camelot-py[ml,ocr]". Structure from the model, text from the PDF (no hallucinated values). engine="combined"(default) and render-freeengine="vector"lattice detection;flavor="auto"per-page routing;flavor="hybrid".- Performance — lattice render skips the PNG round-trip,
get_table_index/text_in_bboxvectorised, one PDF open per call. - Quality-of-life:
Table.confidence,TableList.filter()/stack_contiguous(),per_page=,replace_text=, bytes/file-like input.
Upgrading from 1.0.x
See the migration guide for breaking changes (Python 3.10+, line_scale 40→15, to_excel defaults, default engine="combined", …). Full details in CHANGELOG.md.
Install
pip install --pre camelot-py==2.0.0rc1
v1.0.9
v1.0.8
v1.0.7
v1.0.6
v1.0.4
v1.0.3
v1.0.2
v1.0.1
Changes
- I've addressed a few regressions and documentation issues that came u… (#594) @bosd
- [MRG] Missing os import fixed in example notebooks (#581) @protokoul
- Create dependabot_auto_approve.yml (#576) @bosd
- Fix test: test_stream_no_tables_in_area (#567) @bosd
- Replace deepsource with codecov (#526) @vinayak-mehta
- Replace codecov with deepsource (#525) @vinayak-mehta
- Add pypi classifiers (#524) @vinayak-mehta
- Update notebooks (#522) @vinayak-mehta
🪲 Fixes
- Update .toml and .lock to add pillow as dependency (#554) @DoomedJupiter
- Fixup mypy (#556) @bosd
📚 Documentation
- [MRG] Update to py 3.13 for doc build (#557) @DoomedJupiter
📦 Dependencies
- Bump opencv-python-headless from 4.11.0.86 to 4.12.0.88 in /docs (#584) @dependabot
- Bump actions/download-artifact from 4 to 5 (#593) @dependabot
- Bump virtualenv from 20.31.2 to 20.33.1 in /.github/workflows (#592) @dependabot
- Bump sigstore/gh-action-sigstore-python from 3.0.0 to 3.0.1 (#583) @dependabot
- Bump ghostscript from 0.7 to 0.8.1 in /docs (#580) @dependabot
- Bump crazy-max/ghaction-github-labeler from 5.2.0 to 5.3.0 (#564) @dependabot
- Bump nox from 2025.2.9 to 2025.5.1 in /.github/workflows (#571) @dependabot
- Bump astral-sh/setup-uv from 5 to 6 (#569) @dependabot
- Bump virtualenv from 20.29.3 to 20.31.2 in /.github/workflows (#575) @dependabot
- Bump pip from 24.3.1 to 25.0.1 in /.github/workflows (#542) @dependabot
- Bump virtualenv from 20.28.0 to 20.29.3 in /.github/workflows (#555) @dependabot
- Bump nox from 2024.10.9 to 2025.2.9 in /.github/workflows (#540) @dependabot
- Bump crazy-max/ghaction-github-labeler from 5.1.0 to 5.2.0 (#539) @dependabot
- Bump matplotlib from 3.10.0 to 3.10.1 in /docs (#549) @dependabot
- Update .toml and .lock to add pillow as dependency (#554) @DoomedJupiter
- Bump opencv-python-headless from 4.10.0.84 to 4.11.0.86 in /docs (#533) @dependabot
- Bump codecov/codecov-action from 4 to 5 (#523) @dependabot