2026-10-14: Migrating from 5.6 to 6.0

PyPDFForm 6.0.0 removes deprecated options and raises the minimum Python version. This guide covers the changes from 5.6.0 to 6.0.0, verified against those release tags.

Python and release support

Release	Minimum Python version	Configured support and test window
5.6.0	3.10	3.10–3.14
6.0.0	3.11	3.11–3.15

Upgrade Python 3.10 environments to a supported version before installing 6.0.0. Update your CI matrix and deployment images too. See installation for the current Python requirements and library/CLI installation commands.

PyPDFForm follows Semantic Versioning. Its security policy limits vulnerability fixes to the latest version: at the 6.0.0 release, 6.0.0 is supported and earlier versions are not. Staying on 5.6.0 to retain Python 3.10 compatibility therefore leaves you outside security support. Report potential vulnerabilities through the private GitHub security advisory route described in that policy.

Removed options and replacements

Interface	Removed option	Migration
Python	PdfWrapper(..., preserve_metadata=...)	Remove the argument. Input PDF metadata is preserved automatically; this deprecated switch no longer controls it.
Python	pdf.fill(data, flatten=...)	Use readonly=... for the former read-only behavior. There is no general form-flattening replacement.
CLI	Global --preserve-metadata	Remove the option. Metadata preservation is automatic.
CLI	fill --flatten	Use fill --readonly for read-only fields. There is no general form-flattening option.

In 5.6.0, flatten=True was already a deprecated alias for readonly=True: it set the form fields' read-only flags. It did not flatten the whole form into page content. If both arguments were supplied, either being True enabled read-only fields. When migrating such a call, preserve that combined intent in a single readonly argument.

For example, replace this 5.6.0 call:

from PyPDFForm import PdfWrapper

pdf = PdfWrapper("sample_template.pdf", preserve_metadata=True)
pdf.fill({"test": "test_1"}, flatten=True).write("output.pdf")

with this 6.0.0 call:

from PyPDFForm import PdfWrapper

pdf = PdfWrapper("sample_template.pdf")
pdf.fill({"test": "test_1"}, readonly=True).write("output.pdf")

For the CLI, replace:

pypdfform --preserve-metadata fill sample_template.pdf -f data.yaml --flatten -o output.pdf

with:

pypdfform fill sample_template.pdf -f data.yaml --readonly -o output.pdf

To keep editable fields editable, omit readonly / --readonly. Passing readonly=False does not unlock fields that are already read-only. To change individual fields' editability, use their readonly property.

Removing preserve_metadata=False does not disable preservation either. There is no replacement switch to discard metadata. If you need metadata removal, handle and verify that separately with a tool that provides that capability.

Python calls can silently ignore removed arguments

In 6.0.0, the constructor and fill() still accept general **kwargs. The removed arguments are ignored without a deprecation warning or an unknown-keyword error. For example, pdf.fill(data, flatten=True) can succeed while leaving editable fields editable. Successful execution therefore does not demonstrate that the requested read-only behavior was applied.

Search application code, wrapper functions, configuration dictionaries, and shell scripts for flatten, preserve_metadata, --flatten, and --preserve-metadata. Update forwarded keyword dictionaries as well as direct calls. Reopen representative output PDFs and check field values, read-only flags, metadata, and appearance in the viewers your application uses.

Signatures, read-only fields, and flattening

These capability boundaries are unchanged by the 6.0 migration:

Capability	PyPDFForm behavior
Signature image	Filling a signature field draws the supplied image onto the page. The image provides a visual mark without cryptographic signing.
Signature field	Fields.SignatureField creates an unsigned signature field. Interaction with that field depends on the viewer's support.
Cryptographic signing	PyPDFForm does not provide an API for signing with a certificate or validating digital signatures. Use a tool with those capabilities when required.
Read-only fields	readonly=True sets form-field flags. Those flags can be changed later; they provide neither flattening nor cryptographic integrity protection.
Form flattening	Converting all form fields into page content and removing their interactive fields has no general PyPDFForm API. The former flatten alias only set read-only flags.

Viewer and appearance limitations

Field display and printing depend on the viewer's handling of appearance streams. need_appearances=True asks the viewer to generate them; the viewer must support that request. generate_appearance_streams=True generates them through PyPDFForm's appearance backend. The corresponding CLI options are --need-appearances and --generate-appearance-streams.

See Handling appearance streams for configuration examples and the documented limits on non-ASCII text, multiline fields, and text alignment in generated appearances. Verify representative output in the viewers and print workflows your application supports, especially when it relies on those features. A successful fill or reopened field value alone does not establish correct rendering.