README
¶
pdfcpu: a Go PDF processor
pdfcpu is a PDF processing library written in Go supporting encryption. It provides both an API and a CLI. Supported are all versions up to PDF 1.7 (ISO-32000).
Motivation
This is an effort to build a comprehensive PDF processing library from the ground up written in Go. Over time pdfcpu aims to support the standard range of PDF processing features and also any interesting use cases that may present themselves along the way.
Focus
The main focus lies on strong support for batch processing and scripting via a rich command line. At the same time pdfcpu wants to make it easy to integrate PDF processing into your Go based backend system by providing a robust command set.
Command Set
- annotations
- attachments
- booklet
- boxes
- change owner password
- change user password
- collect
- create
- crop
- decrypt
- encrypt
- extract
- fonts
- grid
- images
- import
- info
- keywords
- merge
- nup
- optimize
- pages
- permissions
- portfolio
- properties
- rotate
- split
- stamp
- trim
- validate
- watermark
Documentation
- The main entry point is pdfcpu.io.
- For CLI examples also go to pdfcpu.io. There you will find explanations of all the commands and their parameters.
- For API examples of all pdfcpu operations please refer to GoDoc.
GoDoc
Reminder
- Always make sure your work is based on the latest commit!
- pdfcpu is still Alpha - bugfixes are committed on the fly and will be mentioned in the next release notes.
- Follow pdfcpu for news and release announcements.
- For quick questions or discussions get in touch on the Gopher Slack in the #pdfcpu channel.
Demo Screencast
(using older version with a smaller command set)
Installation
Download
Get the latest binary here.
Using Go Modules
git clone https://github.com/pdfcpu/pdfcpu
cd pdfcpu/cmd/pdfcpu
go install
pdfcpu version
Using Homebrew (macOS)
brew install pdfcpu
pdfcpu version
Using DNF/YUM (Fedora)
sudo dnf install golang-github-pdfcpu
pdfcpu version
Run in a Docker container
docker build -t pdfcpu .
# mount current folder into container to process local files
docker run -it --mount type=bind,source="$(pwd)",target=/app pdfcpu ./pdfcpu validate -mode strict /app/pdfs/a.pdf
Contributing
What
- Please open an issue if you find a bug or want to propose a change.
- Feature requests - always welcome!
- Bug fixes - always welcome!
- PRs - anytime!
- pdfcpu is stable but still Alpha and occasionally undergoing heavy changes.
How
- If you want to report a bug please attach the very verbose (
pdfcpu cmd -vv ...) output and ideally a test PDF that you can share. - Always make sure your contribution is based on the latest commit.
- Please sign your commits.
Reporting Crashes
Unfortunately crashes do happen :( For the majority of the cases this is due to a diverse pool of PDF Writers out there and millions of PDF files using different versions waiting to be processed by pdfcpu. Sometimes these PDFs were written more than 20(!) years ago. Often there is an issue with validation - sometimes a bug in the parser. Many times even using relaxed validation with pdfcpu does not work. In these cases we need to extend relaxed validation and for this we are relying on your help. By reporting crashes you are helping to improve the stability of pdfcpu. If you happen to crash on any pdfcpu operation be it on the command line or in your Go backend these are the steps to report this:
Regardless of the pdfcpu operation, please start using the pdfcpu command line to validate your file:
pdfcpu validate -v &> crash.log
or to produce very verbose output
pdfcpu validate -vv &> crash.log
will produce what's needed to investigate a crash. Then open an issue and post crash.log or its contents. Ideally post a test PDF you can share to reproduce this. You can also email to hhrutter@gmail.com or if you prefer Slack you can get in touch on the Gopher slack #pdfcpu channel.
If processing your PDF with pdfcpu crashes during validation and can be opened by Adobe Reader and Mac Preview chances are we can extend relaxed validation and provide a fix. If the file in question cannot be opened by both Adobe Reader and Mac Preview we cannot help you!
Contributors
Thanks goes to these wonderful people:
Code of Conduct
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Disclaimer
Usage of pdfcpu assumes you know about and respect all copyrights of any PDF content you may be processing. This applies to the PDF files as such, their content and in particular all embedded resources like font files or images. Credit goes to Renee French for creating our beloved Gopher.
License
Apache-2.0
Powered By
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
pdfcpu
Package main provides the command line for interacting with pdfcpu.
|
Package main provides the command line for interacting with pdfcpu. |
|
internal
|
|
|
corefont/metrics
Package metrics provides font metrics for the PDF standard fonts.
|
Package metrics provides font metrics for the PDF standard fonts. |
|
pkg
|
|
|
api
Package api lets you integrate pdfcpu's operations into your Go backend.
|
Package api lets you integrate pdfcpu's operations into your Go backend. |
|
cli
Package cli provides pdfcpu command line processing.
|
Package cli provides pdfcpu command line processing. |
|
filter
Package filter contains PDF filter implementations.
|
Package filter contains PDF filter implementations. |
|
font
Package font provides support for TrueType fonts.
|
Package font provides support for TrueType fonts. |
|
log
Package log provides a logging abstraction.
|
Package log provides a logging abstraction. |
|
pdfcpu
Package pdfcpu is a PDF processing library written in Go supporting encryption.
|
Package pdfcpu is a PDF processing library written in Go supporting encryption. |
|
pdfcpu/validate
Package validate implements validation against PDF 32000-1:2008.
|
Package validate implements validation against PDF 32000-1:2008. |
|
types
Package types provides pdfcpu's base types.
|
Package types provides pdfcpu's base types. |