pdfcpu can keep PDF work local, but validation still needs judgment

The first decision is not which subcommand to run. It is where the bytes go. pdfcpu is a PDF-processing library and command-line tool written in Go, so it can run inside infrastructure you control instead of requiring a document upload to somebody else's service.

That privacy boundary depends on the deployment. Running the CLI locally is local processing. Embedding the Go API in a local application can be local processing. Putting pdfcpu behind a website and sending the file to its server is still an upload, regardless of how reassuring the button looks.

Release history is available in the project changelog. The project supports PDF versions through PDF 2.0, although its README explicitly describes PDF 2.0 validation as basic and continuously improving. PDF has had decades to acquire compartments, and none of them came with a sensible labeling system.

One tool, two ways in

pdfcpu provides a CLI for direct and scripted file operations, plus a Go API for applications that need PDF processing as part of a larger workflow. The project is licensed under Apache 2.0 and states that it prioritizes correctness, robustness, predictable behavior and minimal external dependencies.

Its operation-oriented design matters. Rather than treating a PDF as merely a stack of visible pages, pdfcpu exposes many of the structures that make the format complicated:

Validation, information and optimization
Splitting, trimming, collecting and merging
Page boxes, cropping, resizing, rotation and zoom
Images, fonts, metadata, keywords and properties
Annotations, bookmarks, attachments and portfolios
Encryption, decryption, permissions, certificates and signatures
Stamps, watermarks, forms and viewer preferences
Grids, booklets, posters, N-up layouts and imported content

The complete command documentation is important because many commands have operation-specific choices that cannot safely be inferred from their names. The general help form documented by the project is:


pdfcpu [command] --help

Use that before incorporating a new command into automation. Guessing at PDF command syntax is an efficient way to discover that your test file was the only uncomplicated PDF in the building.

Start with evidence, then transform

A useful local workflow begins by preserving the original file. My default is to write transformations to a new output and retain the input until the result has passed both structural validation and the application's own acceptance checks.

Start with the documented validation command:


pdfcpu validate input.pdf

For a merge, the README gives this form:


pdfcpu merge merged.pdf in1.pdf in2.pdf

Validate the produced document as a separate step:


pdfcpu validate merged.pdf

That final command is not ceremonial. A successful transformation and a satisfactory result are different claims. Validation addresses PDF structure according to pdfcpu's current implementation; it does not establish that bookmarks, page order, signatures, forms or visible output match the operator's intent.

For batch processing, keep the command, exact pdfcpu version, input identity, output identity and validation result together. This turns an intermittent document failure into a reproducible case rather than a conversation beginning with "one of the invoices did something odd."

The Go API serves the same broader use case when PDF handling belongs inside a Go program rather than a shell pipeline. The project provides separate API documentation, an API test collection and sample programs for application integration. Use those documented entry points instead of parsing CLI messages as an application protocol.

The page is only the lobby

A PDF that looks clean can still contain annotations, attachments, metadata, keywords, document properties, bookmarks or portfolio content. pdfcpu's command catalog exposes these separately because rendered pages do not tell the whole story.

That distinction is particularly important in privacy work. Removing a visible mark does not prove that the associated information disappeared elsewhere in the file. Encryption controls access; it does not remove embedded information. Signature handling addresses integrity and evidence; it is not a substitute for content inspection.

Cropping deserves special suspicion. A visual crop is not evidence that underlying content has been deleted, and the supplied pdfcpu documentation does not describe crop as a redaction feature. Cropping is curtains, not demolition.

Before releasing a sensitive document, decide which structures are allowed to remain and inspect those structures explicitly. The relevant pdfcpu command families include attachments, annotations, keywords, properties, portfolio, images, fonts and extract. Consult each command's help rather than assuming one inspection covers every kind of embedded material.

Where pdfcpu bites

The PDF opens in a viewer, but validation fails

Symptom: Adobe Acrobat Reader or macOS Preview opens the document, while pdfcpu refuses to validate or process it.

Cause: The project treats these files as valuable compatibility cases. A viewer accepting a document does not establish that pdfcpu's parser and validator will accept the same structures.

What to do: Run the project's documented diagnostic command:


pdfcpu validate -vv <file.pdf>

Retain the command and verbose output. If reporting the problem, include a sample only when you have permission to share it and it contains no confidential or personal data.

The file fails in pdfcpu and both reference viewers

Symptom: pdfcpu cannot process the file, and neither Adobe Acrobat Reader nor macOS Preview can open it.

Cause: The project says such a document is unlikely to be processed reliably by pdfcpu. This is a materially different case from a viewer-compatible parser failure.

What to do: Treat the input as suspect. Return to the producing application or obtain a clean source copy instead of repeatedly applying transformations to the damaged file and hoping the fifteenth attempt feels more authoritative.

A PDF 2.0 result is presented as complete conformance proof

Symptom: A workflow reports that a document is fully PDF 2.0 conforming solely because pdfcpu accepted it.

Cause: pdfcpu supports PDF versions through PDF 2.0, but the project explicitly calls its PDF 2.0 validation support basic and continuously improving.

What to do: Scope the claim precisely. Record that the file was validated by the exact pdfcpu version used, along with its output. Do not turn that result into a broader certification that the tool does not claim to provide.

A crop is mistaken for secure redaction

Symptom: Hidden material becomes visible through extraction, alternate page-box handling or later editing even though the released page looked cropped.

Cause: Cropping controls the visible page region. The supplied documentation does not claim that crop securely deletes underlying content.

What to do: Never label cropping as redaction. Use a documented redaction process appropriate to the confidentiality requirement, then inspect the resulting file's underlying content and non-page structures before release.

A signed original is transformed in place

Symptom: Signature integrity or reported signature evidence changes after optimization, merging, cropping, stamping or another document transformation.

Cause: Digital signatures cover defined byte ranges, so later document changes matter. pdfcpu separately documents signature-integrity validation, evidence reporting and signature removal, which should not be collapsed into the vague phrase "signature support."

What to do: Preserve the signed original. Check signature state before transformations, write the transformed document as a new artifact and check it again afterward. Use the dedicated signature documentation for the operation being performed.

A browser workflow is assumed to be local

Symptom: The interface runs in a browser, but inspection shows the PDF being sent to a remote endpoint for processing.

Cause: Browser-based and browser-local are not synonyms. A site can upload a document to a server that runs pdfcpu, while a local CLI invocation processes within the operator's own environment.

What to do: Verify the actual data path. For a no-upload requirement, confirm that PDF bytes do not leave the device. The implementation boundary, not the presence of a browser tab, determines where the document goes.

The diagnostic sample becomes the disclosure

Symptom: A useful compatibility report requires a sample PDF, but the available sample contains confidential material or personal data.

Cause: Parser failures are easiest to reproduce with the triggering file, while public issue systems are inappropriate places for sensitive documents. The project explicitly tells reporters to submit only files they may share.

What to do: Do not upload the original. Reproduce the problem with an authorized, sanitized sample if possible, and follow the project's private reporting process for security vulnerabilities rather than using a public GitHub issue.

References

Important notice. Tap any item to read it in full.

Accuracy is not guaranteed

This article was produced with substantial automated assistance and is published without individual expert verification of every statement. It may contain errors, omissions, oversimplifications, or claims that were accurate when written and have since been superseded. Software, protocols, specifications and best practice in this field change quickly.

Verify before you rely on it

Treat this page as a starting point and a pointer to primary sources, never as an authority in itself. Before acting on anything here, check it against the official documentation, the original publication, or the vendor's own materials, which are linked in the references above. Where this page and a primary source disagree, the primary source is correct and this page is wrong.

No warranty

This content is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of accuracy, completeness, currency, merchantability, or fitness for a particular purpose.

No liability

To the fullest extent permitted by applicable law, pdfb2.io and its authors accept no liability for any loss or damage whatsoever, whether direct, indirect, incidental, consequential or otherwise, arising from use of or reliance on this article. This expressly includes lost time, lost data, damaged samples or specimens, wasted reagents or compute, failed experiments, equipment damage, and commercial loss.

Not professional advice

Nothing here constitutes professional, scientific, engineering, regulatory, safety or legal advice. You remain solely responsible for your own experimental design, safety assessment, regulatory compliance and data handling, and for any code you run or procedure you perform.

About the illustration

Any image accompanying this article is editorial and decorative. It was produced with generative AI, is not a technical diagram, is not to scale, and is not an accurate depiction of any structure, process or result. Do not read measurements, structures or relationships from it.

Third-party names and links

Product, project and organisation names are the property of their respective owners and are used for identification only. Their mention is not endorsement, affiliation or sponsorship in either direction. External links are provided for convenience and we neither control nor are responsible for third-party content.

Corrections

If you find an error, tell us and we will correct or withdraw the page.