opt-pdf(1) General Commands Manual 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.
littleutils 2026 Jan 01 opt-pdf(1)
littleutils 1.4.0 - Generated Wed Feb 18 07:37:21 CST 2026