---
license: apache-2.0
library_name: docling
pipeline_tag: image-to-text
tags:
  - docling
  - table-structure-recognition
  - document-conversion
  - tables
  - pdf
  - preview
---

# TableFormerV2

> [!WARNING]
> **Preview model.** TableFormerV2 is a preview release. Its weights, outputs, and
> integration options can change in future releases without notice. The default
> table structure model in Docling is still
> [TableFormer V1](https://huggingface.co/docling-project/docling-models).

TableFormerV2 is a table structure recognition model for
[Docling](https://github.com/docling-project/docling). It takes an image of a
table and predicts its structure as an
[OTSL](https://arxiv.org/abs/2305.03393) token sequence, together with a
bounding box for each cell. Docling then maps the cells back to the text of the
document to build a `TableItem` in the `DoclingDocument`.

## Model details

| | |
|---|---|
| **Developed by** | IBM Research, for the Docling project |
| **Model type** | Image-to-sequence (table structure + cell boxes) |
| **Parameters** | ~52M (FP32) |
| **Input** | Table crop, resized to 448×448 |
| **Output** | OTSL structure tokens and one bounding box per cell |
| **License** | Apache-2.0 |
| **Status** | Preview |

### Architecture

- **Image encoder:** EfficientNetV2-S backbone with Squeeze-and-Excitation.
- **Spatial mixer:** depthwise separable convolutions (no self-attention in the
  encoder).
- **Structure decoder:** cache-aware Transformer decoder with cross-attention to
  the image features.
- **Bounding-box head:** multi-layer attention decoder that predicts one box per
  cell.

The design is lightweight. It targets fast CPU inference and GPU batch
inference.

The model implementation is in
[`docling-ibm-models`](https://github.com/docling-project/docling-ibm-models)
(`docling_ibm_models.tableformer_v2`).

## Usage with Docling

Install Docling:

```bash
pip install docling
```

Docling downloads the weights from this repository automatically the first time
you use the model. To download them before you run a conversion (for example,
for offline use), run:

```bash
docling-tools models download tableformerv2
```

### Option 1: Use the preset

The fastest way to enable TableFormerV2 is to select it by name.

**CLI:**

```bash
docling report.pdf --table-structure-engine docling_tableformer_v2
```

**Docling Serve / Service Client:** set the `tableformer_v2` preset.

```python
from docling.datamodel.service.options import ConvertDocumentsOptions
from docling.service_client import DoclingServiceClient

options = ConvertDocumentsOptions(table_structure_preset="tableformer_v2")

with DoclingServiceClient(url="http://localhost:5001") as client:
    result = client.convert(source="report.pdf", options=options)
    print(result.document.export_to_markdown())
```

### Option 2: Set the full pipeline options

Use the Python SDK when you need full control over the pipeline. Set
`table_structure_options` to `TableStructureV2Options`:

```python
from docling.datamodel.accelerator_options import AcceleratorOptions
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import (
    PdfPipelineOptions,
    TableStructureV2Options,
)
from docling.document_converter import DocumentConverter, PdfFormatOption

pipeline_options = PdfPipelineOptions(
    do_table_structure=True,
    table_structure_options=TableStructureV2Options(
        # True:  match the predicted cells to the text cells of the PDF.
        # False: use the cells predicted by the model and ignore the PDF cells.
        do_cell_matching=True,
    ),
    accelerator_options=AcceleratorOptions(device="auto", num_threads=8),
)

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options),
    }
)

result = converter.convert("report.pdf")

for table in result.document.tables:
    print(table.export_to_dataframe())
```

To load pre-downloaded weights, set `artifacts_path` on the pipeline options:

```python
pipeline_options = PdfPipelineOptions(
    artifacts_path="/path/to/models",  # contains docling-project--TableFormerV2/
    table_structure_options=TableStructureV2Options(),
)
```

### Options

| Option | Default | Description |
|---|---|---|
| `do_cell_matching` | `True` | Match the predicted cells to the PDF text cells. Set to `False` if PDF cells span more than one column, because this can break the table output. |

## Limitations

- This is a **preview** model. Quality and behavior can change between
  releases.
- On Apple Silicon, the model runs on CPU. Docling does not use MPS for this
  model.
- The model sees only the table crop. Errors in the layout model (missed or
  wrongly cropped tables) propagate to the table structure.

## License

This model is released under the
[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

## Citation

If you use TableFormerV2, please cite Docling:

```bibtex
@misc{Docling,
  author = {Docling Team},
  title = {Docling: An Efficient Open-Source Toolkit for AI-driven Document Conversion},
  url = {https://arxiv.org/abs/2501.17887},
  eprint = {2501.17887},
  archivePrefix = {arXiv},
  doi = {10.48550/arXiv.2501.17887},
  year = {2025}
}
```