img2table: pulling tables out of PDFs and images with OpenCV

Image processing instead of a neural table detector

The positioning is stated in the second paragraph of the readme and it explains the whole design. The design provides a practical and lighter alternative to neural network based solutions, especially for usage on CPU. That is a real constraint rather than a marketing claim, because a neural table detector wants a GPU to be pleasant and an image processing pipeline wants one to be optional. The library is a simple, easy to use, table identification and extraction library based on OpenCV image processing, supporting most common image file formats as well as PDF files. So the architecture is: find the table structures in the page image by looking at lines and borders, work out the cell grid, then read the text inside each cell with an OCR engine you choose. The features list frames the scope as plug-and-play table extraction from heterogeneous documents, including native PDFs, scanned PDFs and images, with minimal configuration, handling of complex table structures such as merged cells, table content extraction by providing support for OCR services and tools, extracted tables returned as a simple object including a Pandas DataFrame representation, and export of extracted tables to an Excel file preserving their original structure.

Images and PDFs have different constructors and different parameters

The two document types are instantiated through separate classes in the document module, and the parameter lists show where they diverge. An Image takes the source, which can be a string, a pathlib.Path, bytes or an io.BytesIO and is required, plus an optional detect_rotation flag defaulting to False that corrects skew and rotation. A PDF takes the same source, plus an optional pages list where None means all pages, the same detect_rotation flag applied to extracted images, and a pdf_text_extraction flag defaulting to True that pulls text from the file for native PDFs. The constructor calls look like this:

from img2table.document import PDF

pdf = PDF(src,
          pages=[0, 2],
          detect_rotation=False,
          pdf_text_extraction=True)

Two details deserve attention. The pages list is by index, so pages=[0, 2] means the first and third pages, which is a cheap way to skip a cover and an index. And PDF pages are converted to images at 200 DPI for table identification, so the detection step always works on a raster image even for a vector PDF. The rotation handling is documented with its limits, supporting skew angles up to 45 degrees and based on a publication by Huang from 2020, and there is a warning that setting detect_rotation to True means image coordinates and bounding boxes returned by other methods might not correspond to the original image, which matters if you are cropping regions from the source using those boxes.

Eight OCR backends, each behind its own install extra

The OCR story is the part with the most configuration, and the design is to keep the backends out of the base install. The standard install supports Tesseract, and each other engine has its own extra: paddle for Paddle OCR, easyocr for EasyOCR, doctr for docTR, surya for Surya OCR, rapidocr for RapidOCR, gcp for Google Vision OCR and aws for AWS Textract OCR. The dependency metadata shows what each pulls in, and the differences matter for deployment size. The Google Cloud Vision extra adds google-cloud-vision and requests, the AWS one adds boto3, the Azure one adds the Azure Cognitive Services computer vision package, and the local ones are heavier, with paddle bringing paddlepaddle and paddleocr and pinning them away from Python 3.14, easyocr bringing easyocr and pillow, surya bringing surya-ocr, doctr bringing python-doctr, and rapidocr bringing rapidocr with onnxruntime and a version cap for Python below 3.11. The base package itself depends on numpy, pypdfium2, opencv-contrib-python, beautifulsoup4 and xlsxwriter, so the core detection and export path stays small. Tesseract, the default, is the one that needs a separate prior installation.

Text is read directly from a native PDF and OCR is skipped

The OCR interface is invoked only when it is needed, and the rule is stated plainly. If possible, meaning for a native PDF, PDF text will be extracted directly from the file and the OCR service or tool will not be called. That is the single most important operational fact about the library, because it decides whether you need an OCR dependency at all. If your inputs are digital PDFs produced by a word processor or a reporting system, the text layer is already there, and the library's job reduces to finding the table geometry and slicing the text into cells. If your inputs are scans or photographs, you need OCR and the choice of backend becomes a real decision. Tesseract is the default and takes a thread count, a language, a page segmentation mode and a directory of traineddata files, and the traineddata directory falls back to an environment variable when it is not given:

from img2table.ocr import TesseractOCR

ocr = TesseractOCR(n_threads=1,
                   lang="eng",
                   psm=11,
                   tessdata_dir="...")

The deep learning based backends download their language models at first use, which the documentation states for PaddleOCR and EasyOCR, so a container image that runs these needs either a warm cache or a network on the first run.

Cython extensions sit under the image processing

The build setup explains where the speed comes from. The package metadata requires Cython and numpy in the build requirements, and there is a setup.py that scans the src directory for .pyx files and compiles each one into an extension module with the numpy include directories, using a language level of 3. The Makefile has a build-ext target that runs the setup script to build the extensions in place, and a clean-ext target that deletes the compiled shared objects and the generated C files. So the heavy image processing work is written in Cython rather than in pure Python, and the pure Python layer sits on top. The development environment is uv based, with a venv target that syncs with all extras and the dev group, a test target that runs pytest with coverage, and a fast-test target that skips the OCR and rotation test directories, which is a sensible split given that the OCR tests are the slow ones. Linting is ruff, type checking is done with ty over the src and tests directories, and the build itself is uv build.

Examples that show the hard cases, not just the easy one

The examples directory is small and its file names are the interesting part, because they name the situations that break table detectors. There is a Basic_usage notebook, an Implicit notebook and a borderless notebook, along with a data directory and a shared utils module. A borderless table is the one with no ruling lines, and it is the classic failure case for a line based detector, so the presence of a dedicated example tells you the library attempts one. The examples are also runnable as a check, since the Makefile has a jupyter target that builds the extension and then starts a notebook server in the examples directory, and an update-examples target that executes each notebook in place with nbconvert, which means the examples are expected to keep working rather than being illustrative only. The build and test workflow lives in GitHub workflows, and the release history shows the project is actively maintained, with 2.0.0 from 2026-05-10 following 1.4.2 from 2025-08-10 and 1.4.1 from 2025-02-09, with the last push on 2026-07-12. The 2.0.0 number after 1.4.2 suggests a breaking release somewhere in between, which is worth checking before you upgrade an existing integration.

Editorial conclusion

img2table is a good fit for a team that has to turn tables in PDFs or images into data, and that wants a CPU friendly approach instead of a neural table detector, since the design is explicitly image processing based and positioned as a lighter alternative to neural network solutions. It is the wrong tool for documents with no ruled lines, since a table detector needs borders to find, and it is the wrong tool if you need the text of a document that is not in a table, since OCR is only invoked for cell content. It is also the wrong tool for a pipeline where the tables are already delimited, since a CSV parse is simpler. Before adopting it, decide on the OCR backend, because each one is a separate install extra with its own dependency weight and its own model download, and check whether your PDFs are native, because for those the text is extracted directly from the file and the OCR service is not called at all. The project is MIT licensed, the last push was on 2026-07-12, and the latest release is 2.0.0 from 2026-05-10.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. xavctn/img2table on GitHub