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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 98.7MB
glibcpy 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)
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)`).
fixInstall `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.
fixEnsure 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.
fixUse `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.