Editing PDF Structure with QPDF
Command Line – QPDF

© Lead Image © Joe Belanger, 123RF.com
Use QPDF to easily make structural changes to your PDFs, including reorganizing pages, creating watermarks, setting encryption options, and changing permissions.
QPDF [1] is a structural editor for PDF files. This description places it in a very specific niche. In its usual output method, it does not edit the content of PDF files – to the extent that editing content is possible, opening a PDF in LibreOffice is generally the easiest way to work. Nor does QPDF import PDFs to different formats – the repositories of major distributions like Debian are full of scripts for that, like pdf2htmlEX
and pdf2svg
. However, if you need to change how a PDF is put together, QPDF is a toolkit that is both comprehensive and more convenient than the assorted scripts that only perform a single function. In fact, by adding options, you can make an entire series of structural edits with a single command. QPDF is especially handy if you no longer have the file from which a PDF was generated and are therefore unable to make a new one with different settings.
QPDF is available in many distributions. If it is not in your distribution's repository, you can download the source code from the project site and build it with the usual trio of commands: configure
, make
, and make install
. The syntax, too, is simple:
qpdf OPTIONS ORIGINAL-FILE OUTPUT-FILE
The output file is not needed for some options, such as those for information. Commands complete without any confirmation except the return to the prompt.
The original file is kept untouched when the command is run, so any errors will not leave you with a corrupted file. Detailed help is available from the command qpdf --help
rather than the man page. QPDF's options are numerous, but the most generally used options can be divided into four main categories: those for general operations, information, page selection, and encryption. In addition, for the adventurous, QPDF can create a file in QDF mode, which will create an output file that can be opened in a text editor.
Options for General Operations
These options determine how QPDF runs, and most can be used alongside other options. They include several unusual features. For example, QPDF's own completion tool can be enabled for either the Bash or Zsh shells with the command
eval $(qpdf --completion-bash)
or
eval $(qpdf --completion-zsh)
If QPDF is not in your path, you will need to give its complete path in order to use completion.
Similarly, if a PDF is protected by a password, in order for QPDF to manipulate it, you will need to give the password with the option --password=PASSWORD
. Without the password, even the information options will not function. If, as often happens, the original PDF has two passwords, one for viewing and one for editing, you will have to enter options for both passwords unless they are the same.
If you want a PDF that displays quickly on the web, select --linearization
. This display makes such changes as reducing the resolution of images so that they load faster. Documents that are all text will benefit minimally from linearization.
Information Options
QPDF's options for retrieving information about a PDF are useful for troubleshooting or for using the QPDF library in automated test suites (Figure 1). The --check
option gives a quick summary of the file structure, encryption, and linearization. The function of other information options is evident from their names (Table 1).
Table 1
Information Options
|
Quickly show encryption settings |
|
Check file integrity and linearization status |
|
Check and show all linearization data |
|
Show the contents of the cross-reference table |
|
Print the n number of pages in the file |
|
Gives info for each page |
|
Shows the object/generation number for each page plus object IDs for images on each page |
|
Check file structure plus encryption and linearization |

Page Selection
QPDF can manipulate the pages shown in the output file. The --pages
option must be used after the basic command, and the page range after the original file. Individual page numbers can be separated by commas, or a range of pages by a dash. Individual pages and ranges can be listed together, so that 3,5,11-14
would be a valid listing of pages. Pages are printed in the order that they are listed, so 11-14,3,5
prints pages 11-14 first in the output file. Other values include z-1
to print in reverse order starting from the last page, and r2-r1
prints the last two pages, while r1-r2
prints the last two pages in reverse order.
Output files can also be created that use multiple source PDFs. When using multiple files, place the --pages=PAGES
option after the name of each source file, rather than after the basic command. After the basic command, you can add --collate
so that the output file begins with the first page or range for the first file in the command, followed by the first page or range for the second file, then the second page or range for the first file, and so on. For example:
qpdf file first.pdf pages=1-4 second.pdf pages=r4-r1 merged.pdf
Still another way to select pages is to define a particular page as either an overlay or an underlay, in effect creating a watermark. Whether you use an overlay or underlay is a matter of choice, usually determined by what you want to be displayed clearly. --overlay
or --underlay
is added after the basic command, and the first page specified for the first file becomes the overlay or underlay for all the pages specified in the second file. Alternatively, where the overlay or underlay file is applied can be specified by adding --to=PAGES
and --from=PAGES
after it.
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Direct Download
Read full article as PDF:
Price $2.95
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Find SysAdmin Jobs
News
-
OpenMandriva Lx 23.03 Rolling Release is Now Available
OpenMandriva "ROME" is the latest point update for the rolling release Linux distribution and offers the latest updates for a number of important applications and tools.
-
CarbonOS: A New Linux Distro with a Focus on User Experience
CarbonOS is a brand new, built-from-scratch Linux distribution that uses the Gnome desktop and has a special feature that makes it appealing to all types of users.
-
Kubuntu Focus Announces XE Gen 2 Linux Laptop
Another Kubuntu-based laptop has arrived to be your next ultra-portable powerhouse with a Linux heart.
-
MNT Seeks Financial Backing for New Seven-Inch Linux Laptop
MNT Pocket Reform is a tiny laptop that is modular, upgradable, recyclable, reusable, and ships with Debian Linux.
-
Ubuntu Flatpak Remix Adds Flatpak Support Preinstalled
If you're looking for a version of Ubuntu that includes Flatpak support out of the box, there's one clear option.
-
Gnome 44 Release Candidate Now Available
The Gnome 44 release candidate has officially arrived and adds a few changes into the mix.
-
Flathub Vying to Become the Standard Linux App Store
If the Flathub team has any say in the matter, their product will become the default tool for installing Linux apps in 2023.
-
Debian 12 to Ship with KDE Plasma 5.27
The Debian development team has shifted to the latest version of KDE for their testing branch.
-
Planet Computers Launches ARM-based Linux Desktop PCs
The firm that originally released a line of mobile keyboards has taken a different direction and has developed a new line of out-of-the-box mini Linux desktop computers.
-
Ubuntu No Longer Shipping with Flatpak
In a move that probably won’t come as a shock to many, Ubuntu and all of its official spins will no longer ship with Flatpak installed.