pdf-form-filler

name	pdf-form-filler
version	1.0.0
author	G-HunterAi
license	MIT
description	Fill PDF forms programmatically with text values and checkboxes. Use when you need to populate fillable PDF forms (government forms, applications, surveys, etc.) with data.
tags	["pdf","forms","automation","documents","data-entry"]
platforms	["macos","linux","windows"]
category	tooling
emoji	📄
requires_bins	["python3"]

PDF Form Filler

Programmatically fill PDF forms with text values and checkboxes. Uses pdfrw to set form field values while preserving appearance streams for proper PDF viewer rendering.

When to Use

Use this skill when you need to:

• Fill existing PDF forms: Government forms, job applications, surveys
• Populate with data: Text fields, checkboxes, radio buttons
• Batch processing: Fill multiple forms with the same data or from a data source
• Automation: Integrate form filling into a workflow or script
• Preserve structure: Keep form editability after filling
• Dynamic field detection: Discover what fields exist in a PDF

When NOT to Use

Do not use this skill for:

• Creating new PDFs from scratch: Use reportlab, weasyprint, or similar
• Editing PDF text or images: Use PDF editor tools
• Merging/splitting PDFs: Use PyPDF2, pdfplumber, or similar
• Complex form layouts: Desktop tools like Adobe Acrobat work better
• Signature fields: This tool doesn't handle digital signatures

Prerequisites

Python 3.8+

Verify your Python version:

python3 --version

Installation

1. Install pdfrw:

pip install pdfrw

2. Verify installation:

python3 -c "import pdfrw; print(pdfrw.__version__)"

Quick Start

1. Install pdfrw

pip install pdfrw

2. Fill a Form

from pdf_form_filler import fill_pdf_form

fill_pdf_form(
    input_pdf="form.pdf",
    output_pdf="form_filled.pdf",
    data={
        "Name": "John Doe",
        "Email": "[e-mail]",
        "Agree": True,  # Checkbox
    }
)

3. Verify Output

Open the output PDF in Adobe Reader or Firefox to verify the form is properly filled.

Features

• Text fields: Set any text value (names, dates, addresses, etc.)
• Checkboxes: Set boolean values (True for checked, False/None for unchecked)
• Appearance states: Properly sets /On and /Off states for PDF viewer rendering
• Preserves structure: Doesn't strip form functionality—can be further edited
• No external dependencies: Uses pdfrw (lightweight, pure Python)
• Field discovery: List available fields before filling
• Partial fills: Only fill specific fields, leave others blank
• Batch processing: Programmatically fill multiple PDFs

How It Works

1. Opens the PDF template using pdfrw
2. Iterates through form fields
3. Sets values for matching field names
4. Handles checkboxes by setting both /V (value) and /AS (appearance state)
5. Saves the filled PDF to output path

Field Name Matching

Field names should match exactly as they appear in the PDF form. Examples:

• Text fields: Full Name, Email Address, Phone Number, Date of Birth
• Checkboxes: Accept Terms, Agree, Yes/No, Confirm
• Date fields: Date, DOB, Start Date, End Date
• Dropdown/Select: Country, State, Position

Discover Field Names

Use list_pdf_fields() to find all available fields in a PDF:

from pdf_form_filler import list_pdf_fields

fields = list_pdf_fields("form.pdf")
for field_name, field_type in fields:
    print(f"{field_name}: {field_type}")

Field types:

• text: Text input field
• checkbox: Boolean checkbox
• radio: Radio button
• dropdown: Dropdown select
• signature: Signature field (not editable)

Examples

Basic Form Fill

from pdf_form_filler import fill_pdf_form

fill_pdf_form(
    input_pdf="job_application.pdf",
    output_pdf="job_application_filled.pdf",
    data={
        "Full Name": "Jane Smith",
        "Email": "[e-mail]",
        "Phone": "555-1234",
        "Position": "Software Engineer",
        "Years Experience": "5",
        "Willing to relocate": True,
        "Available immediately": False,
        "Background check consent": True,
    }
)

Partial Fill

Only fill specific fields, leaving others blank:

data = {"Name": "Jane Doe"}  # Only Name is set
fill_pdf_form("form.pdf", "form_filled.pdf", data)

Dynamic Field Detection

Get all fields and prompt for values interactively:

from pdf_form_filler import list_pdf_fields, fill_pdf_form

fields = list_pdf_fields("form.pdf")
data = {}

for field_name, field_type in fields:
    if field_type == "text":
        data[field_name] = input(f"Enter {field_name}: ")
    elif field_type == "checkbox":
        response = input(f"Check {field_name}? (y/n): ").lower()
        data[field_name] = response == 'y'

fill_pdf_form("form.pdf", "form_filled.pdf", data)

Batch Processing

Fill multiple PDFs with the same data:

import os
from pdf_form_filler import fill_pdf_form

data = {
    "Name": "John Doe",
    "Date": "2026-03-21",
    "Organization": "Acme Corp"
}

input_dir = "forms/"
output_dir = "forms_filled/"

# Create output directory if needed
os.makedirs(output_dir, exist_ok=True)

# Process all PDFs
for filename in os.listdir(input_dir):
    if filename.endswith(".pdf"):
        fill_pdf_form(
            f"{input_dir}{filename}",
            f"{output_dir}{filename}",
            data
        )
        print(f"Filled: {filename}")

Multiple Forms with Different Data

Fill multiple forms with data from a list or CSV:

import csv
from pdf_form_filler import fill_pdf_form

# Read data from CSV
with open("applicants.csv", "r") as f:
    reader = csv.DictReader(f)
    for row in reader:
        fill_pdf_form(
            input_pdf="application_template.pdf",
            output_pdf=f"applications/{row['Name']}_application.pdf",
            data=row
        )

Troubleshooting

Checkboxes not showing visually

Some PDF viewers don't render checkboxes immediately after filling. The value is set correctly (/On or /Off), but visual appearance isn't regenerated immediately.

Solution: Try opening the filled PDF in:

• Adobe Reader (will render automatically)
• Firefox (has good form support)
• Evince or Okular on Linux (usually works)

If still blank, the form may not have appearance streams defined. This is a limitation of the original PDF.

Field names not found

Use list_pdf_fields() to confirm exact field names. PDF forms can have unusual naming:

• Some use non-descriptive names (e.g., Field_1 instead of Full_Name)
• Some have nested field structures that don't show in the list
• Some fields may be read-only or signature-only

from pdf_form_filler import list_pdf_fields

fields = list_pdf_fields("form.pdf")
print(f"Found {len(fields)} fields:")
for name, ftype in fields:
    print(f"  {name} ({ftype})")

Text appears cut off

Some PDFs have narrow text fields. Solutions:

1. Use shorter values: Abbreviate names, dates, addresses
2. Reduce font size: Edit the PDF template to use smaller font
3. Manual editing: Fill programmatically, then manually adjust in Adobe Acrobat
4. Split text: Use multiple fields if available

Permission denied or cannot write output

Check that:

• Output directory exists and is writable
• You have write permissions in the target directory
• The output file isn't already open in another application
• Disk space is available

import os
output_dir = os.path.dirname(output_pdf)
if not os.path.exists(output_dir):
    os.makedirs(output_dir)

Python API Reference

fill_pdf_form(input_pdf, output_pdf, data)

Fill a PDF form with the provided data dictionary.

Parameters:

• input_pdf (str): Path to the template PDF form
• output_pdf (str): Path where filled PDF will be saved
• data (dict): Dictionary of field names → values

Returns: None (writes to output_pdf)

Example:

fill_pdf_form("template.pdf", "filled.pdf", {"Name": "John", "Active": True})

list_pdf_fields(pdf_path)

List all fillable fields in a PDF.

Parameters:

• pdf_path (str): Path to the PDF form

Returns: List of tuples (field_name, field_type)

Example:

fields = list_pdf_fields("form.pdf")
# Returns: [("Name", "text"), ("Agree", "checkbox"), ...]

Works Well With

• doc-converter: Convert filled PDFs to other formats (Word, HTML, etc.)
• browser-automation: Scrape data to fill into PDF forms
• web-scraper: Collect form data from websites to fill PDFs

Implementation

The skill is built on pdfrw, a pure Python PDF library that:

• Doesn't require external dependencies (no Ghostscript, ImageMagick, etc.)
• Handles appearance streams for proper PDF viewer rendering
• Preserves form functionality (forms can be re-edited after filling)
• Works across platforms (macOS, Linux, Windows)

See scripts/fill_pdf_form.py for the implementation using pdfrw.