Last updated: September 11

Efficient PDF optimization with Ghostscript CLI

Kevin van Zonneveld

Co-founder · Amsterdam, The Netherlands ·

Optimizing PDF files is crucial for efficient storage, faster loading, and easier sharing. Ghostscript, an open-source interpreter for PostScript and PDF files, offers a robust command-line interface (CLI) that can significantly reduce PDF size, often without noticeable quality loss.

Introduction to Ghostscript CLI

Ghostscript is a well-established tool for creating, viewing, and transforming PostScript and PDF documents. Through its CLI, you can script or batch-process optimizations that would otherwise require bulky desktop applications.

Set up Ghostscript

Installation differs per platform:

Windows — Download a maintained release matching your system architecture from the official downloads page.
macOS — Homebrew keeps you current:
```
brew install ghostscript
```

Debian/Ubuntu — Use APT:

sudo apt update && sudo apt install ghostscript

Confirm the installation:

gs --version

Basic syntax for optimization

The fundamental command structure looks like this:

gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/screen \
   -dNOPAUSE -dQUIET -dBATCH -sOutputFile=output.pdf input.pdf

Key switches explained:

-sDEVICE=pdfwrite — Specifies that the output should be a PDF.
-dCompatibilityLevel= — Chooses the target PDF specification version.
-dPDFSETTINGS= — Selects a predefined optimization preset (details below).
-dNOPAUSE -dQUIET -dBATCH — Ensures the command runs non-interactively without pausing or printing excessive messages.
-sOutputFile= — Defines the name of the optimized output file.
input.pdf — The original PDF file to be optimized.

PDF optimization presets

The -dPDFSETTINGS option provides convenient presets that bundle common downsampling and compression settings:

/screen — Lowest quality (72 dpi images), smallest file size. Ideal for on-screen viewing where size is critical.
/ebook — Medium quality (150 dpi images), balanced size and quality. Good for e-readers and general use.
/printer — High quality (300 dpi images), suitable for printing.
/prepress — Print-oriented settings with 300 dpi image downsampling. It is not a universal highest-quality setting; compare the output against your requirements.

A typical command for a good balance between size and quality using the /ebook preset:

gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook \
   -dNOPAUSE -dQUIET -dBATCH -sOutputFile=optimized.pdf original.pdf

Choose a compatibility level

Newer PDF viewers handle the latest features, but older devices or software might require compatibility with older PDF specifications. Ghostscript supports levels from 1.3 up to 2.0:

Level	When to use
`1.3`	Legacy support (Acrobat 4+)
`1.4`	Transparency support (Acrobat 5+)
`1.7`	Broader feature set (Acrobat 8+)
`2.0`	Requires a viewer supporting PDF `2.0`

Choosing the lowest compatibility level that meets your audience's needs can sometimes shave off extra bytes. Test level 1.4 when older viewer compatibility is important.

Step-by-step: shrink a PDF

Here are a few examples, starting simple and adding more control:

Using the /ebook preset — A balanced approach:

gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook \
   -dNOPAUSE -dQUIET -dBATCH -sOutputFile=ebook.pdf original.pdf

Using the /screen preset — Prioritizing file size:

gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/screen \
   -dNOPAUSE -dQUIET -dBATCH -sOutputFile=small.pdf original.pdf

Custom settings — Manually controlling image resolution:

gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.7 -dDownsampleColorImages=true \
   -dColorImageResolution=150 -dNOPAUSE -dQUIET -dBATCH \
   -sOutputFile=custom.pdf original.pdf

This example specifically downsamples color images to 150 dpi.

Advanced optimization techniques

For finer control, you can combine presets with additional switches:

gs -sDEVICE=pdfwrite -dCompatibilityLevel=2.0 -dPDFSETTINGS=/ebook \
   -dDetectDuplicateImages=true \
   -dCompressFonts=true -dSubsetFonts=true \
   -dNOPAUSE -dQUIET -dBATCH -sOutputFile=advanced.pdf original.pdf

What these extra flags do:

-dDetectDuplicateImages=true — Finds and deduplicates identical bitmap images within the PDF.
-dCompressFonts=true — Compresses embedded fonts.
-dSubsetFonts=true — Embeds only the characters (glyphs) actually used from each font, rather than the entire font file.

Performance tips

Optimizing large or complex PDFs can be time-consuming. Consider these options to speed things up:

Bound batch concurrency: Process independent PDFs in separate jobs with unique output paths, limiting the number of simultaneous processes to fit your machine's resources.
Measure representative files: Image-heavy and vector-heavy PDFs respond differently to the same settings. Rendering-thread options do not parallelize the pdfwrite device.
Preserve originals: pdfwrite constructs a new document. Check appearance, links, forms, metadata, and file size before replacing an original; a smaller result is not guaranteed.

Practical use cases

Tailor your settings to the intended use:

Web delivery — Use /screen or /ebook, compatibility 1.4, and consider server-side gzip compression for further reduction during transfer.
E-readers — /ebook with font subsetting (-dSubsetFonts=true) usually provides a good reading experience.
Prepress: Use /prepress as a starting point, configure color conversion for your printing workflow, and proof the output. A preset alone does not guarantee the required color result.

Compare file sizes

Compare /screen, /ebook, and your custom settings against the same original files. Record the Ghostscript version, exact command, input and output bytes, and processing time. Check the rendered pages as well: smaller files may have lower image quality or lost document features.

Licensing note

Ghostscript is dual-licensed under the GNU Affero General Public License (AGPL) version 3.0 and a commercial license offered by Artifex Software, Inc. If you distribute Ghostscript, distribute a modified version, or use it in a network service context where users interact with it remotely, ensure your usage complies with the AGPL terms or obtain a commercial license.

Common errors and solutions

If you encounter issues, check these common problems:

gs: command not found — Ghostscript is likely not installed correctly or its location isn't included in your system's PATH environment variable. Verify the installation and PATH setup.
Can't find (or open) font 'FontName' — The PDF uses a font not available to Ghostscript. Install the missing font or add its directory with -sFONTPATH=/path/to/fonts. Prefer embedding the font in the original PDF when its license permits it.
Unable to open the initial device, quitting. followed by Permission denied: Ghostscript doesn't have permission to write the output file. Check the permissions of the output directory.
Invalid destination or similar file errors — Ensure the target path specified with -sOutputFile= exists and is a file path, not just a directory.

Wrap-up

Ghostscript's CLI provides a powerful and flexible way to achieve significant PDF optimization directly from the command line. By experimenting with presets, compatibility levels, and advanced flags, you can find the ideal balance between file size and quality for your specific needs.

If you need to integrate PDF optimization into a larger automated workflow without managing Ghostscript installations yourself, Transloadit’s Document Processing service leverages Ghostscript and other tools in the cloud.