{"id":8158,"library":"fillpdf","title":"FillPDF","description":"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.","status":"active","version":"0.7.3","language":"en","source_language":"en","source_url":"https://github.com/t-houssian/fillpdf","tags":["PDF","form filling","automation","document processing"],"install":[{"cmd":"pip install fillpdf","lang":"bash","label":"Install fillpdf"},{"cmd":"conda install -c conda-forge poppler","lang":"bash","label":"Install Poppler (required for advanced flattening)"}],"dependencies":[{"reason":"Core PDF manipulation library.","package":"pdfrw"},{"reason":"Used for converting PDF pages to images, especially for flattening features.","package":"pdf2image"},{"reason":"Image processing library, used in conjunction with pdf2image.","package":"Pillow"},{"reason":"Also known as `fitz`, used for advanced PDF operations like image and text insertion.","package":"PyMuPDF"},{"reason":"External dependency, required for `flatten_pdf(as_images=True)` mode. Must be installed separately (e.g., via apt, brew, or conda), not pip.","package":"poppler","optional":true}],"imports":[{"note":"The primary functions are exposed via the 'fillpdfs' object within the 'fillpdf' package.","wrong":"import fillpdf","symbol":"fillpdfs","correct":"from fillpdf import fillpdfs"}],"quickstart":{"code":"import os\nfrom fillpdf import fillpdfs\n\n# Create a dummy PDF (replace with your actual fillable PDF path)\n# For demonstration, assume 'template.pdf' exists with fields like 'name', 'age', 'is_active'\n# You would typically create this PDF using a PDF editor.\n\n# Example of getting form fields\n# This step is crucial to know the exact field names in your PDF\ntry:\n    form_fields = fillpdfs.get_form_fields('template.pdf')\n    print(\"Available form fields:\", form_fields)\nexcept FileNotFoundError:\n    print(\"Error: template.pdf not found. Please provide a valid fillable PDF.\")\n    # Create a dummy fillable PDF for testing if not present, e.g., using another library or manually\n    # For a real scenario, 'template.pdf' needs to be a pre-existing fillable PDF.\n    exit()\n\n# Prepare data to fill the PDF\ndata_to_fill = {\n    'name': 'John Doe',\n    'age': '30',\n    'is_active': 'Yes' # For checkboxes, typically 'Yes'/'Off' or similar strings\n}\n\ninput_pdf_path = 'template.pdf'\noutput_filled_pdf_path = 'filled_form.pdf'\noutput_flattened_pdf_path = 'flattened_form.pdf'\n\n# Fill the PDF\nfillpdfs.write_fillable_pdf(\n    input_pdf_path,\n    output_filled_pdf_path,\n    data_to_fill,\n    flatten=False # Set to True to flatten immediately after filling\n)\nprint(f\"Filled PDF saved to {output_filled_pdf_path}\")\n\n# Flatten the filled PDF (make fields uneditable)\nfillpdfs.flatten_pdf(\n    output_filled_pdf_path,\n    output_flattened_pdf_path\n)\nprint(f\"Flattened PDF saved to {output_flattened_pdf_path}\")\n\n# You can also insert images or text at specific coordinates if needed\n# fillpdfs.place_image('image.png', 100, 100, output_flattened_pdf_path, 'output_with_image.pdf', 1)\n# fillpdfs.place_text_box('my_text_field', 'Some extra text', 200, 200, output_flattened_pdf_path, 'output_with_text.pdf', 1)","lang":"python","description":"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."},"warnings":[{"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`.","message":"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)`.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that `input_pdf_path` and `output_pdf_path` are different file paths to avoid conflicts and data loss.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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)`).","error":"FileNotFoundError: [Errno 2] No such file or directory: 'pdftocairo'"},{"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.","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.","error":"ValueError: PDF has no form fields."},{"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).","cause":"The field name you are trying to write to in your `data_dict` does not exist in the target PDF form.","error":"KeyError: 'SomeFieldName'"}]}