OPT-PDF(1)

NAME
opt-pdf - optimize PDF image files using Ghostscript or Poppler

SYNOPSIS
opt-pdf [-h(elp)] [-b(ackup)] [-c(olor) DPI] [-f filelist] [-F(orce)] [-g(ray) DPI] [-m(ono) DPI] [-o(ptimize_for_web)] [-p(ipe)] [-q(uiet)] [-t(ouch)] [-T threads] [-v(erbose)] [-(e)X(tra_pass)] file...

DESCRIPTION
opt-pdf runs existing PDF files through Ghostscript or Poppler in order to make them smaller. This is accomplished using the gs, pdfinfo, and pdftocairo utilities.

OPTIONS

-h  Print help and quit.

-b  Retain the original file by adding a ".bak" suffix.

-c DPI
    Downsample color bitmap images inside the PDF file to a pixel resolution of DPI.

-f file_list
    Read the names of files to be processed from the specified file.

-F  Force an overwrite of input files, even if the new version is larger. This is useful when the goal of an opt-pdf run is to create more proper PDF files rather than smaller ones. This flag also forces opt-pdf to process files that have already been run through Ghostscript or Poppler instead of skipping them as it normally does.

-g DPI
    Downsample grayscale bitmap images inside the PDF file to a pixel resolution of DPI.

-m DPI
    Downsample monochrome bitmap images inside the PDF file to a pixel resolution of DPI.

-o  Write "web optimized" PDF documents, which puts elements of the file into a more linear order and adds "hint" pointers, much like Ghostscript's pdfopt utility. Note that this option will actually make the PDF file slightly larger.

-p  Read the names of files to be processed from stdin.

-q  Quiet output. No output commentary will be printed.

-t  Preserve timestamp on modified files.

-T threads
    Process up to the specified number of files in parallel. The default value is half the multi-threading capability of the CPU, i.e., half the sibling count as listed in /proc/cpuinfo.

-v  Print debugging output from Ghostscript.

-X  Perform an extra pass of processing, where Ghostscript-processed files are run through Poppler and Poppler-processed files are run through Ghostscript.

EXAMPLES

Process a couple of PDF files:
    opt-pdf file001.pdf file002.pdf

Process all PDF images in an directory tree, utilizing half of all cores:
    find . -name "*.pdf" -print | opt-pdf -p

Fully utilize a quad-core system while process all PDF images:
    find . -name "*.pdf" -print | opt-pdf -p -T 4

NOTES
The opt-pdf utility was originally written to reduce the size of overly-large PDF files generated by certain programs (here's looking at you, Pro/Engineer). Additionally, it can sometimes correct files that are not fully compliant with PDF standards. If opt-pdf appears to be malfunctioning, try running it in single-threaded mode by using the -T 1 option. This permits more meaningful error messages to be printed.

CAVEATS
The opt-pdf is not strictly lossless like the opt-gif, opt-jpg, and opt-png utilities. It completely rewrites the PDF file by running it through Ghostscript or Poppler, and it is possible that this will introduce subtle changes. Ghostscript and Poppler are far more complex than utilities that handle only bitmapped images. You have been warned.

SEE ALSO
gs(1), pdfinfo(1), pdfopt(1), pdftocairo(1)

COPYRIGHT
Copyright (C) 2013-2026 by Brian Lindholm. This program is free software; you can use it, redistribute it, and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.