Last updated: May 12, 2025 # Efficient PDF optimization with Ghostscript CLI ![Kevin van Zonneveld](/assets/images/teammates/avatar-kvz-4.jpg?dpl=dpl_C6YH6XrtnwbHLJcm1LDKywQn4CB3) #### Kevin van Zonneveld Co-founder · Amsterdam, The Netherlands · Show bio [](https://x.com/kvz)[](https://github.com/kvz) Optimizing PDF files is crucial for efficient storage, faster loading, and easier sharing. Ghostscript (current stable version 10.05.1 as of April 2025), a powerful 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 the 10.05.1 installer from the[official downloads page⁠](https://www.ghostscript.com/releases/gsdnld.html) (choose`gs10051w32.exe` or `gs10051w64.exe`). * **macOS** — Homebrew keeps you current: ```bash brew install ghostscript ``` * **Debian/Ubuntu** — Use APT: ```bash sudo apt update && sudo apt install ghostscript ``` Confirm the installation: ```bash gs --version # Should output 10.05.1 or your installed version ``` ## Basic syntax for optimization The fundamental command structure looks like this: ```bash 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` — Highest quality (300 dpi images) with color preservation, largest file size. Used for professional printing workflows. A typical command for a good balance between size and quality using the `/ebook` preset: ```bash 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|Spec Year|When to use| |-|-|-| |1.3|2000|Maximum legacy support (Acrobat 4+)| |1.4|2001|Safe default, enables transparency (Acrobat 5+)| |1.7|2006|Broader feature set (Acrobat 8+)| |2.0|2020|Smallest files via modern compression (Acrobat 10+)| Choosing the lowest compatibility level that meets your audience's needs can sometimes shave off extra bytes. Level 1.4 is often a safe starting point. ## Step-by-step: shrink a PDF Here are a few examples, starting simple and adding more control: 1. **Using the `/ebook` preset** — A balanced approach: ```bash gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook \ -dNOPAUSE -dQUIET -dBATCH -sOutputFile=ebook.pdf original.pdf ``` 2. **Using the `/screen` preset** — Prioritizing file size: ```bash gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/screen \ -dNOPAUSE -dQUIET -dBATCH -sOutputFile=small.pdf original.pdf ``` 3. **Custom settings** — Manually controlling image resolution: ```bash 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: ```bash gs -sDEVICE=pdfwrite -dCompatibilityLevel=2.0 -dPDFSETTINGS=/ebook \ -dDetectDuplicateImages=true -dRemoveUnusedResources=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. * `-dRemoveUnusedResources=true` — Strips out resources like fonts or images that are defined but not actually used on any page. * `-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: 1. **Parallelize rendering:** Use `-dNumRenderingThreads=` (e.g., `-dNumRenderingThreads=4`for a quad-core CPU) to utilize multiple processor cores. 2. **Skip interpolation:** Add `-dInterpolateControl=0` if slight image aliasing is acceptable; this can speed up image processing. 3. **Disable transparency:** If your PDF doesn't use transparency or if compatibility with very old viewers is needed, `-dNOTRANSPARENCY` might help. 4. **Batch processing:** If optimizing multiple files, invoke Ghostscript once with multiple input/output pairs if possible, or script it efficiently to avoid the startup overhead for each file. Example incorporating performance flags: ```bash gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook \ -dNumRenderingThreads=4 -dInterpolateControl=0 -dNOPAUSE -dQUIET -dBATCH \ -sOutputFile=fast.pdf original.pdf ``` ## 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` and ensure necessary options for color profile preservation (e.g.,`-dPreserveICCProfiles=true`) are set if required. ## Compare file sizes Here's a sample comparison using a 12-page, image-heavy PDF: |Setting|Pages|Original Size|Result Size|Savings| |-|-|-|-|-| |/screen|12|8.2 MB|1.1 MB|86%| |/ebook|12|8.2 MB|2.4 MB|71%| |Custom (150 dpi)|12|8.2 MB|1.8 MB|78%| *(Values measured with Ghostscript 10.05.1 on macOS. Results will vary based on PDF content.)* ## 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: 1. **`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. 2. **`Can't find (or open) font 'FontName'`** — The PDF uses a font not available to Ghostscript. Install the missing font system-wide, or try the `-dNOPLATFONTS` flag to prevent Ghostscript from using platform-native font rendering. 3. \*\*`\*\*** 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. 4. **`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](/services/document-processing.md) leverages Ghostscript and other tools in the cloud. \#ghostscript-cli#pdf-optimization#reduce-pdf-size#command-line-pdf-tools#ghostscript-examples#document-processing-service ### 👩‍💻 Join 20k+ developers Sign up for our [monthly newsletter](/newsletters.md) to receive direct links to 3 exclusive tech — and 2 product updates. No less, no more. Your email: Get access ## File uploading and encoding. Made simple. Transloadit streamlines file handling for developers, trusted by brands like Coursera and The New York Times. We’re known for a reliable API, top-notch support, and a strong commitment to open source, with projects like [Uppy⁠](https://uppy.io) and [Tus⁠](https://tus.io) setting standards in file processing. [Sign up](/c/)[Book a Demo](https://survey.typeform.com/to/kRg47Xi5) No credit card needed · 5 GB included in the free plan Cancel anytime