commonforms

CommonForms takes a flat PDF — a scanned or exported document with printed blanks, checkboxes, and signature lines but no interactive fields — and produces a version you can actually type into. It detects where the form fields belong, then writes them back into the PDF as AcroForm widgets. It ships both a CLI and a Python API, and runs on CPU by default so you don't need a GPU to try it. The detection is done by two open models, FFDNet-S and FFDNet-L, released alongside the paper CommonForms: A Large, Diverse Dataset for Form Field Detection by Joe Barrow.

How it works

The core task is object detection on a rendered page image: given a picture of a page, find bounding boxes for the fields and classify each one as a text input, checkbox, or signature. Each PDF page is rasterized to an image (default inference size 1600px on the long edge), passed through the detector, and every box above the confidence threshold (default 0.3) becomes a form widget at the corresponding location in the output PDF.

Two model sizes are published on HuggingFace. FFDNet-L is the default and more accurate; FFDNet-S is smaller and faster. The names and the dependency footprint (rfdetr, ultralytics, torch, transformers) point at standard detection backbones — RF-DETR and YOLO-family architectures — rather than anything PDF-specific. The models were trained on the CommonForms dataset, a large and varied collection of real forms that the author also published on HuggingFace; the repo's dataset/ folder holds the preprocessing code used to build it (marked as work in progress).

Detected signatures default to text fields; a flag switches them to actual signature fields. Existing form fields in the input are dropped unless you ask to keep them, so re-running on an already-interactive PDF won't duplicate widgets by default.

Usage

Install into an isolated environment — the dependency set is large and pins recent versions, so a plain pip install into a shared env can upgrade numpy, pillow, and transformers in place:

uv tool install commonforms
# or
pipx install commonforms

CLI, simplest form (CPU, default FFDNet-L):

commonforms input.pdf output.pdf

Common flags: --model FFDNet-S for the smaller model or a path to a custom .pt, --device cuda (or a device index) for GPU, --confidence 0.3 to tune the detection threshold, --image-size 1600 for inference resolution, --fast to trade accuracy for roughly half the CPU runtime, --multiline to let detected text boxes accept multiple lines, --use-signature-fields to emit real signature fields, and --keep-existing-fields to preserve widgets already in the PDF.

The Python API mirrors the CLI — every CLI flag is a keyword argument to prepare_form:

from commonforms import prepare_form

prepare_form(
    "path/to/input.pdf",
    "path/to/output.pdf",
    model="FFDNet-S",
    device="cpu",
    confidence=0.3,
)

Hosted models are also available at detect.semanticdocs.org if you don't want to run inference locally.

Limitations

It detects and places field widgets; it does not read or extract the values a filled form contains — that's a different problem (see structured-output-benchmark for LLM-based document-to-JSON extraction). Detection quality is bounded by the models and their training distribution, so unusual layouts or field types outside the dataset can be missed or misplaced, and the confidence threshold is a blunt knob for that. The install is heavy because of the deep-learning stack, and CPU inference on large documents is slow unless you use --fast or a GPU. The dataset preprocessing code is still marked work in progress. Changing how a PDF looks rather than what it holds is a third problem again — veil does that one, inverting text for dark-mode reading while leaving the images alone.

The license is a custom, non-standard one (GitHub reports it as NOASSERTION); the author asks non-academic users to reach out by email, so check the repository terms before commercial use.

Single-author and model-dependent, so it's on watchlist pending a second maintainer and clearer licensing.

Repo: https://github.com/jbarrow/commonforms — 1,189 stars, custom license (NOASSERTION).