--- title: "Detecting and adding form fields to a PDF document | Nutrient Python SDK" canonical_url: "https://www.nutrient.io/guides/python/editor/detect-and-add-form-fields/" md_url: "https://www.nutrient.io/guides/python/editor/detect-and-add-form-fields.md" last_updated: "2026-05-30T02:20:01.349Z" description: "How to detect form fields in a PDF and add interactive form fields using Nutrient Python SDK." --- # Detecting and adding form fields to a PDF document Scanned forms — tax filings, healthcare intake sheets, lease agreements, expense reports — usually arrive as image-based PDFs. The page shows boxes, checkboxes, and signature lines, but the PDF has no AcroForm structure behind them, so end users can't fill the form in a viewer and downstream tools can't read the values. Adding those fields by hand means measuring rectangles for every blank on every page. This sample shows how to detect form-field regions on each page of a document and add matching AcroForm fields automatically using Nutrient Python SDK. The input can be any document format the SDK supports. If the input isn't already a PDF, the SDK converts it to PDF when you create the editor. [Download sample](https://www.nutrient.io/downloads/samples/python/detect-and-add-form-fields.zip) ## How Nutrient helps Nutrient Python SDK handles the full detection-and-creation pipeline behind a single method call. The SDK takes care of: - Implicitly converting non-PDF inputs (images, multi-page TIFFs, Office documents) to PDF when the editor is created - Rendering each PDF page to a bitmap at the resolution the detection model expects - Running the form-field detection model and classifying each region as text, checkbox, or signature - Mapping image coordinates back to PDF page coordinates (including the Y-axis flip) - Adding a matching AcroForm widget for each detected region with a unique field name The result is a standard PDF with interactive form fields that any viewer can fill or any downstream tool can read. ## Supported field types and limits The current detection model classifies regions into three types: text, checkbox, and signature. The SDK maps them to `PdfTextField`, `PdfCheckBoxField`, and `PdfSignatureField` respectively. Radio buttons aren't yet emitted by the model and are skipped. Detection runs on the rendered page image, so accuracy depends on the visual quality of the original document — clean scans produce better results than heavily compressed or skewed pages. ## Preparing the project Import the classes used in the sample: ```python from nutrient_sdk import Document from nutrient_sdk import PdfEditor from nutrient_sdk import NutrientException ``` ## Detecting and adding form fields The `main()` function opens the source document inside a [context manager](https://docs.python.org/3/reference/datamodel.html#context-managers), creates a PDF editor, and calls `detect_and_add_form_fields()` to process every page in a single call. The context manager closes the document automatically when the block ends, even if an error is raised: ```python def main(): try: with Document.open("input_forms_detection.pdf") as document: editor = PdfEditor.edit(document) editor.detect_and_add_form_fields() ``` `PdfEditor.edit(document)` attaches an editor to the open document. If the document isn't already a PDF, the SDK converts it to PDF at this step so the rest of the pipeline works on a uniform page representation. Calling `editor.detect_and_add_form_fields()` walks every page, runs detection, and adds an AcroForm widget for each detected region. Existing form fields on the document aren't removed — detection only adds new fields and synthesizes unique names so it doesn't collide with anything already present. ## Saving the result Save the modified document to a new file and close the editor. Wrap the call in `try/except` on `NutrientException` to surface any licensing, model-loading, or I/O issue that the SDK reports: ```python editor.save_as("output.pdf") editor.close() except NutrientException as e: print(f"Error: {e}") if __name__ == "__main__": main() ``` ## Conclusion The workflow for auto-populating an image-based form is: 1. Open the source document. 2. Create a `PdfEditor` for the document. 3. Call `detect_and_add_form_fields()` to detect and add fields across every page. 4. Save the result and close the editor. The output is a standard PDF with interactive form fields, so existing PDF viewers can fill the form and downstream tools can read the values without any extra configuration. --- ## Related pages - [Adding a custom page to a PDF document](/guides/python/editor/add-custom-page-to-pdf.md) - [Adding redaction annotations to a PDF document](/guides/python/editor/add-redaction-annotations-to-pdf.md) - [Adding annotations to a PDF document](/guides/python/editor/add-annotations-to-pdf.md) - [Adding free text annotations to a PDF document](/guides/python/editor/add-freetext-annotations-to-pdf.md) - [Adding invisible digital signatures to a PDF document](/guides/python/editor/add-invisible-signature-to-pdf.md) - [Adding interactive form fields to a PDF document](/guides/python/editor/add-form-fields-to-pdf.md) - [Adding shape annotations to a PDF document](/guides/python/editor/add-shape-annotations-to-pdf.md) - [Adding link annotations to a PDF document](/guides/python/editor/add-link-annotations-to-pdf.md) - [Adding stamp annotations to a PDF document](/guides/python/editor/add-stamp-annotations-to-pdf.md) - [Adding sticky note annotations to a PDF document](/guides/python/editor/add-sticky-note-annotations-to-pdf.md) - [Editing PDF metadata with Nutrient Python SDK](/guides/python/editor/editing-pdf-metadata.md) - [Editing PDF form fields](/guides/python/editor/editing-pdf-form-fields.md) - [Adding visible digital signatures to a PDF document](/guides/python/editor/add-visible-signature-to-pdf.md) - [Advanced digital signature workflows](/guides/python/editor/advanced-digital-signatures.md) - [Nutrient Python SDK editor guides](/guides/python/editor.md) - [Merging PDFs](/guides/python/editor/merge-pdf-into-other-pdf.md) - [Managing PDF page order](/guides/python/editor/manage-pdf-page-order.md) - [Filling PDF form fields](/guides/python/editor/fill-pdf-form.md) - [Adding text markup annotations to a PDF document](/guides/python/editor/add-text-markup-annotations-to-pdf.md)