Modify PDF & form fields⚓︎

PyPDFForm lets you modify PDF-level metadata and form field settings in code. You can update document titles, field appearances, and field behavior without altering the PDF form template.

The examples in this section primarily use this PDF.

Change PDF title⚓︎

LibraryCLI

Set the PDF title during PdfWrapper instantiation or via the .title property. Accessing it retrieves the current title.

Instantiate with TitleSet Title via AttributeGet Title via Attribute

from PyPDFForm import PdfWrapper

pdf = PdfWrapper("sample_template.pdf", title="My PDF")

from PyPDFForm import PdfWrapper

pdf = PdfWrapper("sample_template.pdf")
pdf.title = "My PDF"

from PyPDFForm import PdfWrapper

pdf = PdfWrapper("sample_template.pdf", title="My PDF")
print(pdf.title)

Set the same title from the command line with update title:

pypdfform update title sample_template.pdf -t "My PDF" -o output.pdf

Change text field font⚓︎

LibraryCLI

Before changing a text field's font, you must first register the desired font.

After registration, you can apply the registered font to any text field:

from PyPDFForm import PdfWrapper, Widgets

form = PdfWrapper("sample_template.pdf")

# change globally by iterating each text field
for field in form.widgets.values():
    if isinstance(field, Widgets.Text):
        field.font = "your_registered_font"

# or change at each field's widget level
form.widgets["test"].font = "your_registered_font"

form.fill(
    {
        "test": "test_1",
        "check": True,
        "test_2": "test_2",
        "check_2": False,
        "test_3": "test_3",
        "check_3": True,
    },
)

form.write("output.pdf")

In the CLI, provide a .ttf file path for each text field's font value:

data.jsonCommand

{
    "test": {
        "font": "path_to_a_ttf_file"
    },
    "test_2": {
        "font": "path_to_a_ttf_file"
    },
    "test_3": {
        "font": "path_to_a_ttf_file"
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

Change text field font size⚓︎

LibraryCLI

You can change the font size using a numeric value in PyPDFForm:

from PyPDFForm import PdfWrapper, Widgets

form = PdfWrapper("sample_template.pdf")

# change globally by iterating each text field
for field in form.widgets.values():
    if isinstance(field, Widgets.Text):
        field.font_size = 20

# or change at each field's widget level
form.widgets["test"].font_size = 30.5

form.fill(
    {
        "test": "test_1",
        "check": True,
        "test_2": "test_2",
        "check_2": False,
        "test_3": "test_3",
        "check_3": True,
    },
)

form.write("output.pdf")

Set each text field's font_size in JSON:

data.jsonCommand

{
    "test": {
        "font_size": 30.5
    },
    "test_2": {
        "font_size": 20
    },
    "test_3": {
        "font_size": 20
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

Change text field font color⚓︎

LibraryCLI

You can change the font color using an RGB tuple:

from PyPDFForm import PdfWrapper, Widgets

form = PdfWrapper("sample_template.pdf")

# change globally by iterating each text field
for field in form.widgets.values():
    if isinstance(field, Widgets.Text):
        field.font_color = (1, 0, 0)

# or change at each field's widget level
form.widgets["test"].font_color = (0.2, 0, 0.5)

form.fill(
    {
        "test": "test_1",
        "check": True,
        "test_2": "test_2",
        "check_2": False,
        "test_3": "test_3",
        "check_3": True,
    },
)

form.write("output.pdf")

Express each text field's RGB font color as a three-item JSON array:

data.jsonCommand

{
    "test": {
        "font_color": [
            0.2,
            0,
            0.5
        ]
    },
    "test_2": {
        "font_color": [
            1,
            0,
            0
        ]
    },
    "test_3": {
        "font_color": [
            1,
            0,
            0
        ]
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

Change text field alignment⚓︎

LibraryCLI

You can change the alignment of the text filled into a text field by setting its alignment property to an integer value: 0 for left, 1 for center, and 2 for right.

from PyPDFForm import PdfWrapper, Widgets

form = PdfWrapper("sample_template.pdf")

# change globally by iterating each text field
for field in form.widgets.values():
    if isinstance(field, Widgets.Text):
        field.alignment = 1  # center

# or change at each field's widget level
form.widgets["test"].alignment = 2  # right

form.fill(
    {
        "test": "test_1",
        "check": True,
        "test_2": "test_2",
        "check_2": False,
        "test_3": "test_3",
        "check_3": True,
    },
)

form.write("output.pdf")

Set each text field's alignment value in JSON, using 0 for left, 1 for center, and 2 for right:

data.jsonCommand

{
    "test": {
        "alignment": 2
    },
    "test_2": {
        "alignment": 1
    },
    "test_3": {
        "alignment": 1
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

Change text field max length⚓︎

LibraryCLI

You can change the maximum number of characters allowed in a text field:

from PyPDFForm import PdfWrapper, Widgets

form = PdfWrapper("sample_template.pdf")

# change globally by iterating each text field
for field in form.widgets.values():
    if isinstance(field, Widgets.Text):
        field.max_length = 4

# or change at each field's widget level
form.widgets["test"].max_length = 2

form.fill(
    {
        "test": "te",
        "check": True,
        "test_2": "test",
        "check_2": False,
        "test_3": "test",
        "check_3": True,
    },
)

form.write("output.pdf")

Set each text field's max_length in JSON:

data.jsonCommand

{
    "test": {
        "max_length": 2
    },
    "test_2": {
        "max_length": 4
    },
    "test_3": {
        "max_length": 4
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

Enable text field character spacing (combs)⚓︎

LibraryCLI

To enable character spacing in a text field, set its .comb property to True. This spaces out the filled text evenly across the field.

from PyPDFForm import PdfWrapper, Widgets

form = PdfWrapper("sample_template.pdf")

# change globally by iterating each text field
for field in form.widgets.values():
    if isinstance(field, Widgets.Text):
        field.max_length = 4
        field.comb = True

# or change at each field's widget level
form.widgets["test"].max_length = 2
form.widgets["test"].comb = True

form.fill(
    {
        "test": "te",
        "check": True,
        "test_2": "test",
        "check_2": False,
        "test_3": "test",
        "check_3": True,
    },
)

form.write("output.pdf")

Set comb alongside the required max_length values in JSON:

data.jsonCommand

{
    "test": {
        "max_length": 2,
        "comb": true
    },
    "test_2": {
        "max_length": 4,
        "comb": true
    },
    "test_3": {
        "max_length": 4,
        "comb": true
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

Warning

This property only takes effect when the text field also has a max_length set.

Enable multiline text field⚓︎

LibraryCLI

To enable multiline input for a text field, set its .multiline property to True. This lets it accept paragraph-style input:

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template.pdf")

form.widgets["test"].multiline = True

form.fill(
    {
        "test": "test_1\ntest_1",
        "check": True,
        "test_2": "test_2\ntest_2",
        "check_2": False,
        "test_3": "test_3\ntest_3",
        "check_3": True,
    },
)

form.write("output.pdf")

Set multiline to true for fields that should accept paragraph-style input:

data.jsonCommand

{
    "test": {
        "multiline": true
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

Change checkbox/radio button size⚓︎

LibraryCLI

You can change the size of a checkbox or a group of radio buttons using a numeric value:

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template.pdf")

form.widgets["check"].size = 50
form.widgets["check_2"].size = 40
form.widgets["check_3"].size = 60

form.fill(
    {
        "check": True,
        "check_2": True,
        "check_3": True,
    },
)

form.write("output.pdf")

Set each checkbox's size, or each radio button group's size, in JSON:

data.jsonCommand

{
    "check": {
        "size": 50
    },
    "check_2": {
        "size": 40
    },
    "check_3": {
        "size": 60
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

LibraryCLI

To modify the options available in a dropdown field, assign a new list of strings to the .choices attribute of the corresponding field. For example, the following snippet updates the dropdown_1 field in this PDF form with a new set of choices:

Default Export ValuesCustom Export Values

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template_with_dropdown.pdf")

form.widgets["dropdown_1"].choices = ["", "apple", "banana", "cherry", "dates"]

form.write("output.pdf")

If the export values should differ from the displayed options, specify a list of tuples for the .choices attribute. The first value of each tuple is the displayed option, and the second value is the export value:

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template_with_dropdown.pdf")

form.widgets["dropdown_1"].choices = [
    ("", "blank_export_value"),
    ("apple", "apple_export_value"),
    ("banana", "banana_export_value"),
    ("cherry", "cherry_export_value"),
    ("dates", "dates_export_value"),
]

form.write("output.pdf")

Put the replacement dropdown choices in JSON. Use strings for default export values or two-item arrays for custom export values:

data.jsoncustom_export.jsonCommand

{
    "dropdown_1": {
        "choices": [
            "",
            "apple",
            "banana",
            "cherry",
            "dates"
        ]
    }
}

{
    "dropdown_1": {
        "choices": [
            [
                "",
                "blank_export_value"
            ],
            [
                "apple",
                "apple_export_value"
            ],
            [
                "banana",
                "banana_export_value"
            ],
            [
                "cherry",
                "cherry_export_value"
            ],
            [
                "dates",
                "dates_export_value"
            ]
        ]
    }
}

pypdfform update field sample_template_with_dropdown.pdf -f data.json -o output.pdf

LibraryCLI

Before changing a dropdown field's font, you must first register the desired font.

After registration, you can apply the registered font to any dropdown field:

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template_with_dropdown.pdf")

form.widgets["dropdown_1"].font = "your_registered_font"

form.write("output.pdf")

In the CLI, provide a .ttf file path for the dropdown field's font value:

data.jsonCommand

{
    "dropdown_1": {
        "font": "path_to_a_ttf_file"
    }
}

pypdfform update field sample_template_with_dropdown.pdf -f data.json -o output.pdf

LibraryCLI

You can change a dropdown field's font size using a numeric value in PyPDFForm:

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template_with_dropdown.pdf")

form.widgets["dropdown_1"].font_size = 30

form.write("output.pdf")

Set the dropdown field's font_size in JSON:

data.jsonCommand

{
    "dropdown_1": {
        "font_size": 30
    }
}

pypdfform update field sample_template_with_dropdown.pdf -f data.json -o output.pdf

LibraryCLI

You can change a dropdown field's font color using an RGB tuple:

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template_with_dropdown.pdf")

form.widgets["dropdown_1"].font_color = (1, 0, 0)

form.write("output.pdf")

Express the dropdown field's RGB font color as a three-item JSON array:

data.jsonCommand

{
    "dropdown_1": {
        "font_color": [
            1,
            0,
            0
        ]
    }
}

pypdfform update field sample_template_with_dropdown.pdf -f data.json -o output.pdf

Change field name⚓︎

PyPDFForm lets you rename existing fields by updating their keys.

LibraryCLI

Update Multiple FieldsUsing Index for Fields with the Same Key

To change the key of the first text field from test to test_text and the second text field from test_2 to test_text_2 in this PDF, use:

from PyPDFForm import PdfWrapper

form = (
    PdfWrapper("sample_template.pdf")
    .update_widget_key("test", "test_text")
    .update_widget_key("test_2", "test_text_2")
)
form.commit_widget_key_updates()

form.write("output.pdf")

If multiple fields share the same key, use the index parameter to choose which one to update. For example, to change the second row's text field from Description[0] to Description[1] in this PDF, use:

from PyPDFForm import PdfWrapper

form = PdfWrapper("733.pdf").update_widget_key(
    "Description[0]", "Description[1]", index=1
)
form.commit_widget_key_updates()

form.write("output.pdf")

Provide the old field keys and their new_key values to update rename:

Update Multiple FieldsUsing Index for Fields with the Same Key

data.jsonCommand

[
    {
        "test": {
            "new_key": "test_text"
        }
    },
    {
        "test_2": {
            "new_key": "test_text_2"
        }
    }
]

pypdfform update rename sample_template.pdf -f data.json -o output.pdf

data.jsonCommand

[
    {
        "Description[0]": {
            "new_key": "Description[1]",
            "index": 1
        }
    }
]

pypdfform update rename 733.pdf -f data.json -o output.pdf

Change field editability⚓︎

LibraryCLI

The readonly property of each form field controls its editability. Setting readonly to True flattens the field, making it uneditable, while setting it to False unflattens it, making it editable. The following example makes different form fields editable in this PDF form after they have been flattened:

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template_with_dropdown.pdf")

form.fill(
    {
        "test_1": "test_1",
        "test_2": "test_2",
        "test_3": "test_3",
        "check_1": True,
        "check_2": True,
        "check_3": True,
        "radio_1": 1,
        "dropdown_1": 0,
    },
    flatten=True,
)
form.widgets["test_2"].readonly = False  # text
form.widgets["check_3"].readonly = False  # checkbox
form.widgets["radio_1"].readonly = False  # radio button group
form.widgets["dropdown_1"].readonly = False  # dropdown

form.write("output.pdf")

The following example starts with a filled, flattened form and then makes selected fields editable again by setting readonly to false:

fill.jsoneditable.jsonCommand

{
    "test_1": "test_1",
    "test_2": "test_2",
    "test_3": "test_3",
    "check_1": true,
    "check_2": true,
    "check_3": true,
    "radio_1": 1,
    "dropdown_1": 0
}

{
    "test_2": {
        "readonly": false
    },
    "check_3": {
        "readonly": false
    },
    "radio_1": {
        "readonly": false
    },
    "dropdown_1": {
        "readonly": false
    }
}

pypdfform fill sample_template_with_dropdown.pdf -f fill.json -o flattened.pdf --flatten
pypdfform update field flattened.pdf -f editable.json -o output.pdf

Change field visibility⚓︎

LibraryCLI

The hidden property of each form field controls its visibility. Setting hidden to True hides the field, while setting it to False makes it visible:

from PyPDFForm import PdfWrapper

form = PdfWrapper("sample_template.pdf")
form.widgets["test"].hidden = True

form.write("output.pdf")

Set hidden to true or false for the fields whose visibility should change:

data.jsonCommand

{
    "test": {
        "hidden": true
    }
}

pypdfform update field sample_template.pdf -f data.json -o output.pdf

Modify PDF & form fields⚓︎

Change PDF title⚓︎

Change text field font⚓︎

Change text field font size⚓︎

Change text field font color⚓︎

Change text field alignment⚓︎

Change text field max length⚓︎

Enable text field character spacing (combs)⚓︎

Enable multiline text field⚓︎

Change checkbox/radio button size⚓︎

Change dropdown field choices⚓︎

Change dropdown field font⚓︎

Change dropdown field font size⚓︎

Change dropdown field font color⚓︎

Change field name⚓︎

Change field editability⚓︎

Change field visibility⚓︎