# gmft narrows PDF table extraction to tables and lets a transformer do the layout

> gmft is a Python library that finds and reconstructs tables in PDFs using Microsoft's Table Transformer, and it deliberately extracts nothing else. It suits a pipeline that needs structured tables out of scientific PDFs, and it depends on torch and transformers rather than a set of native extractors.

**conjuncts/gmft** — Lightweight, performant, deep table extraction

- Repository: https://github.com/conjuncts/gmft
- Stars: 542 · Forks: 41
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/conjuncts-gmft

## Detection and formatting are two separate objects you compose

The library is organised as a pipeline with two halves that you wire together yourself, and the quickstart shows the shape. `AutoTableDetector` finds candidate tables on a page, `AutoTableFormatter` turns a detected table into structured output, and `CroppedTable` is what comes back. The example imports them from `gmft.auto`, alongside `PyPDFium2Document` from `gmft.pdf_bindings`, and then builds the two objects directly:

```python
detector = AutoTableDetector()
formatter = AutoTableFormatter()
```

That separation is the design worth understanding, because it is what makes the library modular and what makes it replaceable at one end. You can detect with the transformer and format with your own logic, or keep both. The detection step works on a page, so the loop is over pages of a document, and the result accumulates into a list of cropped tables. The document object is closed explicitly with `doc.close()` once you are done, and the comment in the example flags that it is done once you are done with the document, which matters when you are looping over thousands of files.

## The quickstart is a page loop, and it closes the document when done

The complete example is short enough to read in full, which is unusual for a library that does as much as this one does. Here is the whole flow:

```python
def ingest_pdf(pdf_path): # produces list[CroppedTable]
    doc = PyPDFium2Document(pdf_path)
    tables = []
    for page in doc:
        tables += detector.extract(page)
    return tables, doc

tables, doc = ingest_pdf("path/to/pdf.pdf")
doc.close() # once you're done with the document
```

Three things in that snippet carry the design. The document is opened per file, so a batch job opens and closes one document per PDF rather than holding them all. The page loop is explicit, which means you can decide per page whether to run detection, and you can interleave other work. The tables list is a plain Python list, so nothing in the library forces a particular data structure on your pipeline. The bulk extract notebook and the demo notebook linked from the documentation cover the fuller versions of these flows, and the readthedocs usage page and config guide are linked as the reference.

## The base model is Table Transformer, and its training set explains its strengths

gmft does not implement its own layout detection. It relies on Microsoft's Table Transformer, which the documentation calls qualitatively the most performant and reliable of the many alternatives, and cites Smock and co-authors' PubTables-1M paper, with the note that the model is pretrained on PubTables-1M and works best with scientific papers. That single fact explains most of what follows in the documentation. Because the model was trained on scientific tables, it handles implicit table structure very well, meaning tables where the cell boundaries are not drawn but implied by the alignment of the text. The failure modes the documentation names are correspondingly specific: OCR issues, merged cells, and false positives. It also notes that the text remains highly usable even when the structure is imperfect, and that alignment of a value to its row and column header stays very accurate because of the underlying procedural algorithm. The model itself is described as very efficient, and it is the reason the package can run without a GPU.

## It runs on CPU, and the documentation claims about ten times faster than alternatives

The performance claim is specific enough to check and specific enough to qualify. A benchmark run on Colab's CPU indicates about 1.381 seconds per page, and converting to a dataframe takes about 1.168 seconds per table. From those two numbers the documentation derives that gmft is about 10x faster than alternatives such as unstructured, nougat, and open-parse or unitable on CPU. Two design decisions carry that. The first is scope: gmft focuses on table extraction, so figures, titles and sections are not extracted at all, and skipping them is the saving. The second is that OCR is usually unnecessary, because PDFs already contain text with positional data, and using that existing data drastically speeds up inference. For images or scanned PDFs, the bounding boxes can be exported for further processing rather than being OCR'd in place. A third choice is in the PDF layer itself, where PyPDFium2 is selected for its high throughput and its permissive licence.

## No external extractors, but you install torch and transformers yourself

The dependency story has a wrinkle that will cost you an afternoon if you are not expecting it. The documentation says gmft does not require any external dependencies such as detectron2, poppler, paddleocr or tesseract, which is true of the extras but not of the whole stack, because the next paragraph says to install `transformers` and `pytorch` with the necessary GPU or CPU options before installing gmft, and that the library also relies on `pypdfium2` and `transformers`. The packaged dependencies in the project metadata confirm the shape: pypdfium2, transformers, torch, pillow, pandas, matplotlib, tabulate, typing_extensions and torchvision are all listed, with a comment on the transformers pin noting the need for the no_timm revision and a dilation workaround for 5.x configs. The install itself is one command:

```bash
git clone https://github.com/conjuncts/gmft
cd gmft
pip install -e .
pip install pytest
```

So in practice the environment needs a working torch install first, and the library is best treated as a set of components around a model rather than a self-contained package.

## Six output formats, and images are the one meant for a second model

The export options are listed as a set, and they cover both machine and human consumption. You can get a pandas dataframe. You can get output by extension, with markdown, latex, html, csv, json and others. You can get a list of text with positions. You can get a cropped image of the table. And you can get the table caption. The cropped image is the interesting one, because the documentation points out that cropped images can be passed into a vision recognizer, naming GPT-4 vision, and the Mathpix, Adobe, Google, Amazon and Azure services, or simply saved to disk for human evaluation. That is a deliberate design: rather than trying to read the table itself in every case, gmft can hand a clean crop to whatever recognition stack you already trust. The format list also explains the dependency on pillow and tabulate, and the pandas dependency is what makes the dataframe path cheap.

## Multi-header, spanning cells and rotated tables arrived in v0.3

The version history is a good guide to which real-world table shapes the library now handles. As of gmft v0.3, the library supports multiple-column headers, enabled with `TATRFormatConfig.enable_multi_header = True`, spanning cells, enabled with `TATRFormatConfig.semantic_spanning_cells = True`, and rotated tables. Those three flags map onto the three ways a table can defeat a naive reader. A table with a two-level column header has a value that belongs to a column identified by two stacked labels. A table with a cell that spans two columns has a value that belongs to neither column alone. A rotated table has its axes turned relative to the page. Enabling a flag is a trade rather than a free win, since each one makes the reconstruction rule more demanding, and the documentation presents them as supported rather than default. The other documented limitation is worth repeating because it is the most common source of bad output: false positives, which the documentation names as references, indexes and large columnar text, false negatives, and no OCR support at all.

## The documentation tells you when to use a different tool

There is a section of this project dedicated to the case where you should not use it, and it is more useful than a feature list. The reasoning is that gmft focuses on tables and aims to maximise performance on tables alone, so if you need other document features like figures or a table of contents, the documentation says you may want a different tool and lists several by name, including marker, nougat, open-parse, docling, unstructured, surya, deepdoctection and DocTR. It also singles out one for a specific case, saying that for table detection img2table is excellent for tables with explicit, solid cell boundaries. That is the real alternative to consider, and the difference in approach is precise. A table with drawn gridlines can be detected with geometry, which is fast and deterministic and needs no model at all, while an implicit table with no borders has to be inferred from the text layout, which is what the transformer does and what a geometry method cannot do. If your PDFs have visible rules, a border-based detector is simpler and probably faster. If they do not, you need a model, and then gmft is one of the shortlisted options.

## Conclusion

gmft is a sound choice for a batch pipeline that needs tables out of a large set of scientific PDFs and nothing else, since the model does the layout work and the outputs can go straight into a dataframe, a CSV or a cropped image for a downstream recognizer. It is a poor fit for general document parsing, because the documentation itself says figures, titles and sections are not extracted, and it is a poor fit for scanned documents, because OCR is not supported and the failure modes list includes OCR issues. Before adopting it, install `transformers` and `pytorch` yourself, since the library does not pull them in, check the comparison notebooks against your own documents rather than trusting the general claim, and note that the last push to the repository was on 2026-07-24 with release v0.4.4 published the same day.

## FAQ

### How do I install gmft for PDF table extraction?

Run pip install gmft, but install transformers and pytorch first with the GPU or CPU options you need, because the library relies on them and does not require external extractors like detectron2, poppler, paddleocr or tesseract. The packaged dependencies also include pypdfium2, pillow, pandas, matplotlib, tabulate, typing_extensions and torchvision.

### What model does gmft use to detect tables?

It relies on Microsoft's Table Transformer, which is pretrained on PubTables-1M and works best with scientific papers. The documentation says it handles implicit table structure very well, and names OCR issues, merged cells and false positives as the current failure modes.

### Does gmft support scanned PDFs and OCR?

There is no OCR support. The documentation says that in most cases OCR is not necessary because PDFs already contain text positional data, and that for images or scanned PDFs the bounding boxes can be exported for further processing instead.

### What output formats can gmft produce?

A pandas dataframe, output by extension such as markdown, latex, html, csv and json, a list of text with positions, a cropped image of the table, and the table caption. The cropped image can be passed into a vision recognizer or saved to disk for human evaluation.

## Sources

- [conjuncts/gmft on GitHub](https://github.com/conjuncts/gmft)
- [Issues](https://github.com/conjuncts/gmft/issues)
- [License: MIT](https://github.com/conjuncts/gmft/blob/main/LICENSE)
- [README](https://github.com/conjuncts/gmft/blob/main/README.md)
- [Releases](https://github.com/conjuncts/gmft/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/conjuncts-gmft