Skip to content


Choose a tag to compare
@hhrutter hhrutter released this 24 Dec 10:31
· 241 commits to master since this release


This years' Xmas release introduces two new commands:

The general focus of this release is handling PDF page boundaries:

  • Media Box
  • Crop Box
  • Trim Box
  • Bleed Box
  • Art Box

Starting with this release existing pdfcpu commands like stamp, watermark, nup, grid and import
now honour Media Box and Crop Box for selected pages where applicable.

Also wherever applicable use your favourite display unit which is one of: points, mm, cm or inches.
The default display unit is points in the PDF user space or whatever is defined by pdfcpu's config.yml located in pdfcpu's conf dir.
Use the optional flag -u on the command line. Read more about Common Flags.


The new boxes command allows the manipulation of page boundaries.
List, add or remove page boundaries for selected pages:

pdfcpu boxes list    [-p(ages) selectedPages] '[boxTypes]' inFile
pdfcpu boxes add     [-p(ages) selectedPages] description  inFile [outFile]
pdfcpu boxes remove  [-p(ages) selectedPages] 'boxTypes'   inFile [outFile]

Read more about box descriptions.

The following command sets an absolute Trim Box in user space and assigns it in turn to Bleed Box for page 2 only:
pdfcpu box add -pages 2 'trim:[10 10 50 50], bleed:trim' in.pdf out.pdf

Let's define a Crop Box expressed by a 1cm margin within the Media Box for all pages using the available command shortcuts:
pdfcpu b a -u cm 'c:1' in.pdf out.pdf


The new crop command is a shortcut for pdfcpu boxes add 'crop:description' inFile [outFile]:

pdfcpu crop [-p(ages) selectedPages] description inFile [outFile]
  • A box may be defined via absolute or relative positioning.
  • A relative position is expressed with respect to the applicable parent box.
  • The Media Box serves as the parent for Crop Box.
  • The Crop Box serves as the parent for Trim, Bleed and Art Boxes.

Please refer to the PDF Specification 14.11.2 Page Boundaries for details.

Crop a 500 x 500 points region with lower left corner in the origin:
pdfcpu crop '[0 0 500 500]' in.pdf

Crop relative to Media Box using a 20mm margin:
pdfcpu crop -u mm '20' in.pdf

Crop relative to Media Box using a 10% margin:
pdfcpu crop '10%' in.pdf


Introducing the optional sort flag:
pdfcpu merge [-m(ode) create|append] [-sort] outFile inFile...

From now on you can ensure that files you want to merge are sorted alphabetically prior to merging.

This may be useful in scenarios like:
pdfcpu merge -sort out.pdf *.pdf


One notable improvement to the api is a facility that lets you apply a mix of image, text and PDF watermarks in one go:
Here the idea is to prepare a map of watermarks and then pass that on to the api.
Depending on which level you are working (File, Reader or PDFContext based) there is a choice of:

  • func AddWatermarksMapFile(inFile, outFile string, m map[int]*pdfcpu.Watermark, conf *pdfcpu.Configuration) error
  • func AddWatermarksMap(rs io.ReadSeeker, w io.Writer, m map[int]*pdfcpu.Watermark, conf *pdfcpu.Configuration) error
  • func (ctx *Context) AddWatermarksMap(m map[int]*Watermark) error

Check out some tests demonstrating this feature at stampVersatile_test.go.

Thanks 💚

There are also numerous bug fixes as well as improvements to the initial parsing, reading and validation of PDF files.
This means that all of you who have been tireless reporting validation errors and crashes ensure that with this release
pdfcpu is capable of digesting an even bigger variety of PDF files coming from different sources.

Special thanks go to Kroum Tzanev for his input and suggestions dealing with page boundaries on the CLI.

This release is the result of all combined efforts by all of you who make up the small but fine pdfcpu community.
Thank you so much and keep the issues coming..


90dd9ab Fix #268
229c707 Fix #264, #265
8047d8c Add cli sort flag for merge, see PR #247
610b532 Fix #258
c282db5 #259
dbe4587 Fix #256
057a52e Fix #262
0e486a3 Fix #210, #216
cd73588 Fix #252
7139eb0 Fix #250
07b1917 Extend info cmd
d4921f9 Fix #245
ad6c2cc Improve attachment handling
017c943 Add Benoit Kugler as contributor
4dee3f9 Fix #236
a2ddad1 Fix missing reader size
d1b2230 Fix encoding handling for keywords, properties
0b3fcc7 Fix parsing errors
298e390 Fix #241
3e2e8d5 Fix #244
c780c6f Fix #244
ce70bec Fix #238