Getting Started with PDF Forms Flattener: Flatten Your First PDF in Under 10 Minutes

You have your activation key (if not, “Before You Start” has you covered!). Here is how to go from installation to a successfully flattened PDF in under 10 minutes.

This guide covers the four operations you will use most: basic installation and verification, flattening a single PDF, importing data before flattening, and converting XFA form fields to AcroForm. For the full parameter reference, the documentation is at docs.datalogics.com.

 

Before You Start

You will need: your PDF Forms Flattener activation key, the installer file for your operating system (.exe for Windows, .bsx for Linux), and at least one PDF with form fields to test with.

If you do not have a trial key yet, request one at datalogics.com/flatten-pdf-forms. No credit card required.

 

Step 1: Install and Verify

 

Windows

Run the .exe installer. Accept the license agreement, choose your installation directory, and paste your activation key when prompted. The installer adds PDFFormsFlattener to your system path.

Open a Command Prompt or PowerShell window and run:

PDFFormsFlattener --help

You should see the help output listing available parameters. If you see a "command not found" error, verify that the installation directory is in your system PATH.

 

Linux

Navigate to the directory containing the .bsx installer and make it executable:

chmod +x PDFFormsFlattener.bsx

./PDFFormsFlattener.bsx

Follow the prompts and paste your activation key when asked. After installation, verify from your terminal:

PDFFormsFlattener --help

If the command is not found, check whether the install directory is in your PATH and add it if needed.

 

Step 2: Flatten Your First PDF

Run the basic flatten command:

PDFFormsFlattener --input
    form.pdf --output flattened.pdf --flatten true

Replace form.pdf with the path to your test PDF. Replace flattened.pdf with your desired output path.

The command completes silently on success. Open flattened.pdf in any PDF viewer. You should see the document with all form data visible as permanent text, but no interactive fields when you click on the form field areas.

The original form.pdf is not modified.

 

Step 3: Import Data Before Flattening

If you want to populate a form from an external data file before flattening, use the --import parameter.

For AcroForms with an XML data file:

PDFFormsFlattener --input
    form.pdf --output output.pdf --import data.xml --flatten true

For XFA forms with an XFD data file:

PDFFormsFlattener --input
    xfa-form.pdf --output output.pdf --import formdata.xfd --flatten true

Supported import formats: FDF, XFDF, XML for AcroForms; XFD, XDP, XML for XFA.

The tool imports the data, populates the fields, and immediately flattens the result into the output PDF. This is the populate-then-lock workflow used in automated document generation pipelines.

 

Step 4: Export Data Before Flattening

To extract form field data before you flatten:

PDFFormsFlattener --input
    form.pdf --export extracted-data.xml

This writes the current field values to extracted-data.xml without modifying the PDF. You can then flatten the PDF separately or push the data to your database or CRM before the form fields are locked.

 

Step 5: Convert XFA to AcroForm

If you are working with XFA forms that are still in active use and you want to preserve interactivity (rather than flatten to a static PDF), use the --convert flag:

PDFFormsFlattener --input
    xfa-form.pdf --output acrof-form.pdf --convert true

The output contains AcroForm fields in place of the XFA fields. The form remains interactive and opens correctly in Chrome, Firefox, mobile viewers, and any AcroForm-compatible PDF tool.

Test the output carefully if your XFA form contains complex conditional logic or dynamic layout features, as not all XFA behaviors translate to AcroForm equivalents.

 

Batch Processing a Directory

To process an entire directory of PDFs:

PDFFormsFlattener --input
    /path/to/input-forms/ --output /path/to/output-forms/ --flatten true

The output directory must exist before you run the command. PDF Forms Flattener processes every .pdf file in the input directory and writes flattened copies to the output directory with matching filenames.

 

Common Issues

"Activation key invalid": Double-check that you are pasting the key exactly as provided. Keys are case-sensitive and should not contain extra spaces.

"File not found": Verify the path to your input PDF. On Windows, use backslashes or wrap the path in quotes if it contains spaces.

"Output directory does not exist": Create the output directory before running the batch command.

For other errors, the User Guide on the Documentation site includes the full error code reference.

 

Next!

Once you have your first flatten running, explore the full parameter set in the documentation: annotation appearance generation, specific XFA handling options, and output validation settings.

Questions? Try out our AI assistant, Scout, or contact us online or via Discord.