Registry / serialization / fillpdf

fillpdf

JSON →
library0.7.3pypypi✓ verified 90d ago

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.

pip install fillpdf
INSTALL
IMPORT
SIG · FILLPDF
F
fillpdf
serializationpythonv0.7.3
Install
3.5s avg
Import
1427ms
Disk
97MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.7.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 98.7MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 1.427s · 99MB
97MB installed
● package 97MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

fillpdfs
✓ from fillpdf import fillpdfs
✗ import fillpdf
The primary functions are exposed via the 'fillpdfs' object within the 'fillpdf' package.

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)
Debug
Known issues
breakingThe `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`.
affects: All versions
gotchaThe 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.
affects: All versions
gotchaWhen 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.
affects: All versions
gotchaCheckbox 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.
affects: All versions
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'pdftocairo'
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.
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'
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).
Upgrade
Version history
0.7.3latest on PyPI · released May 3, 2024
Audit
Dependencies
pdfrwrequiredCore PDF manipulation library.
pdf2imagerequiredUsed for converting PDF pages to images, especially for flattening features.
PillowrequiredImage processing library, used in conjunction with pdf2image.
PyMuPDFrequiredAlso known as `fitz`, used for advanced PDF operations like image and text insertion.
poppleroptionalExternal dependency, required for `flatten_pdf(as_images=True)` mode. Must be installed separately (e.g., via apt, brew, or conda), not pip.
Agent activity
38 hits · last 30 days
node
36
Resources
fillpdf — pip install fillpdf · libregistry