Skip to main content
Version: 9.x

Optimize a PDF

Rewrites a PDF to make it smaller, without losing quality.

POST/forms/pdf/optimize
Form data
filesfile[]required

The PDFs.

archivesfile[]

ZIP files Gotenberg unpacks: each entry counts as a file uploaded under files.

downloadFromjson

URLs Gotenberg downloads first, as if you had uploaded the files. Each entry takes a url, and optionally extraHttpHeaders.

Options
objectStreamsboolean

Packs objects into compressed object streams.

Default: true

dedupboolean

Stores identical streams once.

Default: true

recompressImagesboolean

Recompresses images without losing quality.

Default: true

subsetFontsboolean

Keeps only the glyphs the document shows.

Default: true

Response

The PDF, or a ZIP of the PDFs when you send several.

The route also takes the headers. An error answers a status and a message: see Errors.

curl \
  --request POST http://localhost:3000/forms/pdf/optimize \
  --form files=@report.pdf \
  -o report.pdf

Gotenberg rewrites the whole file. It packs objects into compressed streams, stores identical streams once, recompresses images without losing quality, and keeps only the glyphs the document shows. This report goes from 23 to 20 KB. A page with large images shrinks more: a Chromium page with a few loses a third.

Optimize what you make​

Put optimize after the stages that change the content, such as a merge:

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@report.pdf \
  --form files=@annex.pdf \
  --form 'stages=[
    { "op": "merge" },
    { "op": "optimize" }
  ]' \
  -o documents.pdf

A conversion takes it too:

curl \
  --request POST http://localhost:3000/forms/libreoffice/convert \
  --form files=@report.docx \
  --form 'stages=[
    { "op": "optimize" }
  ]' \
  -o report.pdf

Turn a pass off​

Each pass runs unless you turn it off: objectStreams, dedup, recompressImages and subsetFonts. Recompressing large images takes time, for instance:

curl \
  --request POST http://localhost:3000/forms/pdf/optimize \
  --form files=@report.pdf \
  --form recompressImages=false \
  -o report.pdf

Signed and encrypted PDFs​

A rewrite removes signatures, so a signed PDF answers 400: optimize first, then sign. A rewrite also writes an encrypted PDF decrypted, so an encrypted PDF answers 400 unless the stages decrypt or encrypt it as well:

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@encrypted.pdf \
  --form 'stages=[
    { "op": "decrypt", "password": "secret" },
    { "op": "optimize" }
  ]' \
  -o report.pdf

A PDF/A-1 stays conformant: Gotenberg leaves out the object streams PDF/A-1 forbids.

Lower the image quality​

optimize never lowers the quality of an image. To trade quality for size, set it where the PDF is made: LibreOffice's nativeQuality and nativeReduceImageResolution, or smaller images in the HTML you send Chromium.

In a list of stages​

The stage also runs in a list on /forms/pdf/pipe, and on the PDFs a Chromium or LibreOffice conversion makes, in its stages field:

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@report.pdf \
  --form 'stages=[
    { "op": "optimize" }
  ]' \
  -o report.pdf