FillPDF

0.7.3 · active · verified Thu Apr 16

fillpdf is a Python library designed to simplify filling and flattening PDF forms. It leverages `pdfrw` (specifically building on `pdfrw2`), `pdf2image`, `Pillow`, and `PyMuPDF` to provide functionalities such as listing form fields, writing data to fields, flattening PDFs (making them non-editable), inserting images and text, and rotating pages. The library is currently at version 0.7.3 and sees active, though somewhat sporadic, development and releases.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'pdftocairo'
```
cause The `poppler` utility, which provides tools like `pdftocairo` and `pdftoppm`, is missing from your system's PATH. `fillpdf` relies on `pdf2image` which in turn depends on `poppler` for image conversions (e.g., `flatten_pdf(as_images=True)`).

fix Install `poppler-utils` (or `poppler` on macOS/conda) on your operating system. For example: `sudo apt-get install poppler-utils` (Debian/Ubuntu), `brew install poppler` (macOS), or `conda install -c conda-forge poppler`.
```
ValueError: PDF has no form fields.
```
cause You are attempting to use `get_form_fields` or `write_fillable_pdf` on a PDF that does not contain any editable form fields. This can happen with scanned documents or PDFs that have already been flattened.

fix Ensure that the input PDF (`input_pdf_path`) is a valid fillable form. You can verify this by opening the PDF in a reader like Adobe Acrobat and checking if you can type into fields.
```
KeyError: 'SomeFieldName'
```
cause The field name you are trying to write to in your `data_dict` does not exist in the target PDF form.

fix Use `fillpdfs.get_form_fields('your_pdf.pdf')` to print all available field names in your PDF and ensure your `data_dict` keys match these names exactly (case-sensitive).

Warnings

breaking The `fillpdf` library relies on external system dependencies, most notably `poppler`, for certain functionalities like converting PDF pages to images (e.g., for some flattening modes). This dependency is not installed via pip and must be installed manually on your operating system (e.g., `apt install poppler-utils` on Debian/Ubuntu, `brew install poppler` on macOS, or `conda install -c conda-forge poppler`). Failing to install `poppler` can lead to `FileNotFoundError` or unexpected behavior when using `flatten_pdf(as_images=True)`.
Fix: Manually install `poppler` via your system's package manager or conda: `conda install -c conda-forge poppler` or refer to OS-specific instructions for `poppler-utils`.
gotcha The term 'flattening' a PDF can be ambiguous. `fillpdf`'s `flatten_pdf` function primarily converts form fields into static content, making them uneditable. However, the exact rendering of these 'flattened' fields might vary across different PDF viewers if the underlying metadata for form fields is simply marked as read-only rather than completely removed. Some viewers (e.g., Bluebeam Revu) may not display the filled data in their preview pane if not truly 'flattened' to content streams, even if the data is present when the PDF is opened fully.
Fix: Test generated PDFs across target PDF viewers. If full 'flattening' (removal of all form metadata) is critical for compatibility, investigate `flatten_pdf(as_images=True)` which requires `poppler`, or consider converting the PDF entirely to an image or rasterizing it if supported by your use case.
gotcha When using `write_fillable_pdf`, `flatten_pdf`, or other functions, using the same path for both the `input_pdf_path` and `output_pdf_path` can lead to `FileNotFoundError`, `PermissionError`, or corrupted files due to concurrent access or overwriting issues. Always use distinct paths for input and output files.
Fix: Ensure that `input_pdf_path` and `output_pdf_path` are different file paths to avoid conflicts and data loss.
gotcha Checkbox fields in PDFs often expect specific string values (e.g., 'Yes', 'On', 'Off', 'X', ' ') rather than standard boolean `True`/`False`. Incorrect values for checkboxes will result in them not being checked or deselected as expected.
Fix: Use `fillpdfs.get_form_fields()` to inspect the field properties and determine the exact string values required for checkboxes in your specific PDF template. Common values are 'Yes' for checked and 'Off' for unchecked.

Install

pip install fillpdf Install fillpdf
conda install -c conda-forge poppler Install Poppler (required for advanced flattening)

Imports

fillpdfs
wrong:
```
import fillpdf
```
correct:
```
from fillpdf import fillpdfs
```
The primary functions are exposed via the 'fillpdfs' object within the 'fillpdf' package.

Quickstart

This quickstart demonstrates how to list the fields in a PDF, fill those fields with a dictionary of data, and then optionally flatten the resulting PDF to make the fields non-editable. Ensure you have a fillable PDF (`template.pdf`) with known field names. For checkboxes, use specific string values like 'Yes' or 'Off' as dictated by your PDF form.

import os
from fillpdf import fillpdfs

# Create a dummy PDF (replace with your actual fillable PDF path)
# For demonstration, assume 'template.pdf' exists with fields like 'name', 'age', 'is_active'
# You would typically create this PDF using a PDF editor.

# Example of getting form fields
# This step is crucial to know the exact field names in your PDF
try:
    form_fields = fillpdfs.get_form_fields('template.pdf')
    print("Available form fields:", form_fields)
except FileNotFoundError:
    print("Error: template.pdf not found. Please provide a valid fillable PDF.")
    # Create a dummy fillable PDF for testing if not present, e.g., using another library or manually
    # For a real scenario, 'template.pdf' needs to be a pre-existing fillable PDF.
    exit()

# Prepare data to fill the PDF
data_to_fill = {
    'name': 'John Doe',
    'age': '30',
    'is_active': 'Yes' # For checkboxes, typically 'Yes'/'Off' or similar strings
}

input_pdf_path = 'template.pdf'
output_filled_pdf_path = 'filled_form.pdf'
output_flattened_pdf_path = 'flattened_form.pdf'

# Fill the PDF
fillpdfs.write_fillable_pdf(
    input_pdf_path,
    output_filled_pdf_path,
    data_to_fill,
    flatten=False # Set to True to flatten immediately after filling
)
print(f"Filled PDF saved to {output_filled_pdf_path}")

# Flatten the filled PDF (make fields uneditable)
fillpdfs.flatten_pdf(
    output_filled_pdf_path,
    output_flattened_pdf_path
)
print(f"Flattened PDF saved to {output_flattened_pdf_path}")

# You can also insert images or text at specific coordinates if needed
# fillpdfs.place_image('image.png', 100, 100, output_flattened_pdf_path, 'output_with_image.pdf', 1)
# fillpdfs.place_text_box('my_text_field', 'Some extra text', 200, 200, output_flattened_pdf_path, 'output_with_text.pdf', 1)

view raw JSON →