Extract PDF Images Safely with pdfimages

Marketing wants the original photo out of a PDF, not a screenshot, and pdfimages gets it out intact. It lists and extracts the embedded images into a separate directory, leaving the document untouched. It uses Poppler 24.02.0, provided here by poppler-utils version 24.02.0-1ubuntu9.9. Allow about ten minutes for a small PDF, plus time to check the extracted files.

This guide assumes a readable PDF and a shell. Extraction normally needs no elevated privileges; do not use sudo unless the input or destination is genuinely inaccessible to your user. The command can write many files, so pick an empty or newly created destination directory before you start.

1. Check the installed tool

Confirm the command resolves to the binary you expect and record its version. These are read-only checks:

$ command -v pdfimages
/usr/bin/pdfimages
$ dpkg-query -W -f='${Package} ${Version}\n' poppler-utils
poppler-utils 24.02.0-1ubuntu9.9
$ pdfimages -v 2>&1 | head -n 2
pdfimages version 24.02.0
Copyright 2005-2024 The Poppler Developers - http://poppler.freedesktop.org

The manual installed with this package describes itself as version 3.03, but the executable reports Poppler 24.02.0. Use the executable's own output when recording what actually ran.

2. List embedded images before extracting them

Use -list for a read-only inventory. With this option, do not supply an image-root:

$ pdfimages -list /path/to/document.pdf

Each row covers one image or mask, reporting page, image number, type, embedded width and height, colour space, bits per component, encoding, resolution and size. These are properties of the embedded image: width and height are not the dimensions a PDF viewer happens to render it at.

• Several rows can belong to one visible picture. Transparency shows up as a separate image and mask, and the manual says a mask or soft mask immediately follows its image.
• Do not assume image number 1 is the first photograph. Every row is not necessarily a standalone picture suitable for sharing.

Keep a long inventory around for later comparison by redirecting it to a text file:

$ pdfimages -list /path/to/document.pdf > image-inventory.txt
$ test -s image-inventory.txt && echo "inventory written"
inventory written

Redirection replaces an existing file, so pick a new name or use a temporary file first if that matters.

3. Extract into a new directory

Create a destination with a name that makes its purpose obvious. This changes the filesystem, so check the path before running it:

$ mkdir -p pdfimages-output
$ test -d pdfimages-output && echo "ready: pdfimages-output"
ready: pdfimages-output
$ pdfimages /path/to/document.pdf pdfimages-output/image
$ find pdfimages-output -maxdepth 1 -type f -printf '%f\n' | sort

The second argument is an output root, not a directory. Each extracted file gets a name such as image-000.jpg or image-001.ppm depending on the image and the options chosen; the exact list is document-specific. Keep the original PDF untouched and treat every generated file as disposable until checked.

By default, non-monochrome images are written as PPM and monochrome images as PBM. Those formats are lossless but can dwarf the source PDF in size. Ask for PNG or TIFF explicitly if you need ordinary image files for review.

4. Choose an output format deliberately

Use -png to make PNG the default for images not being copied in a native encoded format:

$ mkdir -p pdfimages-png
$ pdfimages -png /path/to/document.pdf pdfimages-png/image
$ file pdfimages-png/image-*

Use -tiff when TIFF suits your next tool better:

$ mkdir -p pdfimages-tiff
$ pdfimages -tiff /path/to/document.pdf pdfimages-tiff/image
$ file pdfimages-tiff/image-*

The output of file depends on the PDF. A wildcard matching no files is a shell error in some shells, so check the directory with find if extraction produced nothing.

If the PDF contains JPEG, JPEG2000, JBIG2 or CCITT data, the native options -j, -jp2, -jbig2 and -ccitt preserve those encodings rather than converting them. The combined -all enables all four native modes, and selects TIFF for CMYK images and PNG for everything else. Native output is not automatically easier to edit: JBIG2 and CCITT extraction can create companion files and parameters.

5. Restrict pages and make filenames useful

Limit the scan with -f for the first page and -l for the last, both inclusive:

$ mkdir -p pdfimages-pages-3-5
$ pdfimages -f 3 -l 5 -png /path/to/document.pdf pdfimages-pages-3-5/image
$ find pdfimages-pages-3-5 -maxdepth 1 -type f -printf '%f\n' | sort

This reduces work and keeps unrelated images out of a large document, but it does not mean image numbers 3 through 5: numbering still follows the images encountered during the scan.

Add -p when page numbers in the filenames will help trace an image back to its source:

$ mkdir -p pdfimages-page-names
$ pdfimages -p -png /path/to/document.pdf pdfimages-page-names/image
$ find pdfimages-page-names -maxdepth 1 -type f -printf '%f\n' | sort

Read the resulting names rather than assuming a particular zero-padding scheme. Page numbers are included by contract; exact names and extensions still depend on the input and chosen format.

6. Handle passwords and failures carefully

A PDF may need a user password before it reads at all. Supply it with -upw only when you have a legitimate password:

$ pdfimages -upw 'REPLACE_WITH_PDF_PASSWORD' -list /path/to/protected.pdf

Passwords placed directly in a shell command can end up in shell history and process listings. Prefer a private session and clear the command from history afterwards; do not paste a real password into a shared terminal, ticket or script.

Check the exit status when scripting:

$ pdfimages -list /path/to/document.pdf
$ status=$?
$ printf 'pdfimages exit status: %s\n' "$status"
pdfimages exit status: 0

Documented statuses: 0 for no error, 1 when the PDF cannot be opened, 2 when an output file cannot be opened, 3 for a PDF-permission error and 99 for another error. A successful exit confirms the command finished, not that every extracted image is the one you wanted. Check the inventory and open representative outputs with a trusted image tool.

7. Avoid accidental overwrites and recover cleanly

Do not point the output root at an existing collection until you know how the command behaves for that document. The safest recovery is to stop, inspect the generated names, and move the whole new directory aside rather than deleting files immediately:

$ mv pdfimages-output pdfimages-output-review
$ find pdfimages-output-review -maxdepth 1 -type f -print

That only renames the directory. If you no longer need the extracted files, review them first, then remove the directory explicitly with rm -r pdfimages-output-review. That deletion is irreversible, so keep it out of an unattended command. None of the extraction commands here modify the source PDF.