Scripting PDFs with PDFtk Server (formerly Pdftk): Examples and Best Practices

PDFtk Server (formerly Pdftk): A Quick Guide to Command-Line PDF ToolsPDFtk Server (formerly Pdftk) is a lightweight, reliable command-line utility for manipulating PDF documents. It’s designed for automation, scripting, and environments where a GUI isn’t practical. This guide covers what PDFtk Server can do, how to install it, common commands and use cases, tips for scripting and automation, troubleshooting, and alternatives.

What is PDFtk Server?

PDFtk Server is a command-line tool for merging, splitting, encrypting, decrypting, repairing, stamping, and rotating PDF files. It’s the server-oriented (non-GUI) version of Pdftk and is suitable for automated workflows, batch jobs, and integration into scripts or backend services. PDFtk works with most PDF versions and is known for a simple syntax and robust performance on large files.

Key features

• Merge multiple PDFs into one file.
• Split a PDF into individual pages or page ranges.
• Extract specific pages to a new PDF.
• Rotate pages by 90/180/270 degrees.
• Burst a PDF into single-page files.
• Repair damaged PDFs where possible.
• Encrypt (owner/user passwords) and decrypt PDFs.
• Apply and remove PDF metadata.
• Stamp or background PDFs with another PDF (watermarks or letterhead).
• Fill PDF form fields (with an FDF or XFDF file) and generate FDF from a PDF.
• Output page-level bookmarks and rotate/save page labels.

Installation

PDFtk Server is available for Linux, macOS, and Windows. Installation packages and methods vary by platform.

• On Debian/Ubuntu derivatives, packages may be available via apt (pdftk or pdftk-server), or via third-party repositories if removed from main repos.
• On Fedora/RHEL systems, check repositories or use a prebuilt binary.
• macOS users can install via Homebrew (brew install pdftk-java), which provides a Java-based build compatible with typical PDFtk commands.
• Windows users can download an installer from the project site or use third-party builds.

Note: There are two common modern distributions: the original C++ Pdftk (older) and pdftk-java or PDFtk Server builds maintained using Java. Command syntax is generally the same across builds.

Basic command syntax

The general PDFtk command format looks like:

pdftk input1.pdf input2.pdf cat output merged.pdf 

Commands commonly used include:

• merge: combine files

  
  pdftk A=one.pdf B=two.pdf cat A B output combined.pdf 

• split (burst):

  
  pdftk input.pdf burst output pg_%02d.pdf 

• extract pages:

  
  pdftk input.pdf cat 1-3 5 output extracted.pdf 

• rotate pages:

  
  pdftk input.pdf cat 1-endeS output rotated.pdf 

  (S = rotate 90 degrees clockwise; use W for 90° counterclockwise, N for no rotation, and E for 180°)

• encrypt:

  
  pdftk input.pdf output encrypted.pdf owner_pw OWNERPASSWORD user_pw USERPASSWORD 

• decrypt:

  
  pdftk secured.pdf input_pw USERPASSWORD output unsecured.pdf 

• stamp/background:

  
  pdftk original.pdf stamp stamp.pdf output stamped.pdf pdftk original.pdf background bg.pdf output backgrounded.pdf 

• fill form fields:

  
  pdftk form.pdf fill_form data.fdf output filled.pdf flatten 

• generate FDF from form:

  
  pdftk form.pdf generate_fdf output data.fdf 

Examples and use cases

1. Merge dozens of invoices into a single archive before sending:

   pdftk *.pdf cat output all-invoices.pdf 

2. Split a large scan into single-page images for OCR or indexing:

   pdftk scan.pdf burst output page_%03d.pdf 

3. Rotate a scanned PDF where pages are rotated 90 degrees:

   pdftk scan.pdf cat 1-endS output rotated_scan.pdf 

4. Apply a company letterhead (single-page PDF) as header to every page:

   pdftk doc.pdf stamp letterhead.pdf output doc_with_header.pdf 

5. Secure documents by setting an owner password and a weaker user password:

   pdftk report.pdf output report_secured.pdf owner_pw secret owner_pw allow DegradedPrinting 

6. Automate form filling from a CSV: convert CSV to FDF/XFDF then

   pdftk template.pdf fill_form data.fdf output filled.pdf flatten 

Scripting tips

• Use filename variables and loops in shell scripts to process many files.
• Combine pdftk with tools like Ghostscript, ImageMagick, or qpdf for tasks pdftk doesn’t handle (e.g., compressing PDFs, image conversion).
• When batch-processing, check exit codes and standard error for failures; script simple retries for occasional I/O errors.
• For Windows PowerShell, use foreach-object and call pdftk.exe with proper quoting for paths containing spaces.

Example Bash loop to add a watermark to all PDFs in a folder:

for f in *.pdf; do   pdftk "$f" stamp watermark.pdf output "watermarked/$f" done 

Troubleshooting common issues

• “Unable to find X”: Ensure pdftk is installed and in PATH; verify binary name (pdftk vs pdftk-java).
• Corrupted output or errors on certain PDFs: try qpdf or Ghostscript to repair first, or use pdftk’s repair by decompressing and recompressing with Ghostscript.
• Permissions/ownership errors: check read/write permissions on input/output directories.
• Missing features on Java builds: pdftk-java aims for compatibility but edge cases exist; test scripts after switching builds.
• Large files: ensure sufficient disk space for temporary files; pdftk may create temp files during processing.

Alternatives and when to choose PDFtk

Use PDFtk when your needs are primarily: merging/splitting, stamping/backgrounds, simple encryption, and form filling from scripts.

Security considerations

• Be careful with passwords and sensitive data in command history; avoid storing plain passwords in scripts. Use environment variables or secure secret stores when scripting encryption/decryption.
• Validate input PDFs from untrusted sources; malformed files can cause crashes or unexpected behavior.
• When automating on shared systems, write outputs to isolated directories and set appropriate permissions.

Further reading and resources

• Official project pages and GitHub repositories for pdftk, pdftk-java, and forks.
• Man pages: run pdftk --help or man pdftk for a full list of commands and options.
• Community examples and scripts for batch form-filling, automated stamping, and CI/CD PDF tasks.

PDFtk Server remains a pragmatic, low-overhead tool for command-line PDF manipulation. For most server-side or scripted PDF workflows — merging, splitting, stamping, and form filling — it provides an efficient, easy-to-learn interface.