qpdf
An option summary appears below. Please see the documentation for details.
If @filename appears anywhere in the command-line, each line of filename
will be interpreted as an argument. No interpolation is done. Line
terminators are stripped. @- can be specified to read from standard input.
The output file can be - to indicate writing to standard output, or it can
be --replace-input to cause qpdf to replace the input file with the output.
Note that when contradictory options are provided, whichever options are
provided last take precedence.
Basic Options
-------------
--version show version of qpdf
--help show command-line argument help
--show-crypto show supported crypto providers; default is first
--completion-bash output a bash complete command you can eval
--completion-zsh output a zsh complete command you can eval
--password=password specify a password for accessing encrypted files
--is-encrypted silently exit 0 if the file is encrypted or 2
if not; useful for shell scripts
--requires-password silently exit 0 if a password (other than as
supplied) is required, 2 if the file is not
encrypted, or 3 if the file is encrypted
but requires no password or the supplied password
is correct; useful for shell scripts
--verbose provide additional informational output
--progress give progress indicators while writing output
--no-warn suppress warnings
--warning-exit-0 exit with code 0 instead of 3 if there are warnings
--linearize generated a linearized (web optimized) file
--replace-input use in place of specifying an output file; qpdf will
replace the input file with the output
--copy-encryption=file copy encryption parameters from specified file
--encryption-file-password=password
password used to open the file from which encryption
parameters are being copied
--encrypt options -- generate an encrypted file
--decrypt remove any encryption on the file
--password-is-hex-key treat primary password option as a hex-encoded key
--suppress-password-recovery
do not attempt recovering from password string
encoding errors
--pages options -- select specific pages from one or more files
--collate causes files specified in --pages to be collated
rather than concatenated
--rotate=[+|-]angle[:page-range]
rotate each specified page 90, 180, or 270 degrees;
rotate all pages if no page range is given
--split-pages=[n] write each output page to a separate file
--overlay options -- overlay pages from another file
--underlay options -- underlay pages from another file
Note that you can use the @filename or @- syntax for any argument at any
point in the command. This provides a good way to specify a password without
having to explicitly put it on the command line.
If none of --copy-encryption, --encrypt or --decrypt are given, qpdf will
preserve any encryption data associated with a file.
Note that when copying encryption parameters from another file, all
parameters will be copied, including both user and owner passwords, even
if the user password is used to open the other file. This works even if
the owner password is not known.
The --password-is-hex-key option overrides the normal computation of
encryption keys. It only applies to the password used to open the main
file. This option is not ordinarily useful but can be helpful for forensic
or investigatory purposes. See manual for further discussion.
The --rotate flag can be used to specify pages to rotate pages either
90, 180, or 270 degrees. The page range is specified in the same
format as with the --pages option, described below. Repeat the option
to rotate multiple groups of pages. If the angle is preceded by + or -,
it is added to or subtracted from the original rotation. Otherwise, the
rotation angle is set explicitly to the given value. You almost always
want to use + or - unless you are certain about the internals of the PDF
you are working with.
If --split-pages is specified, each page is written to a separate output
file. File names are generated as follows:
* If the string %d appears in the output file name, it is replaced with a
zero-padded page range starting from 1
* Otherwise, if the output file name ends in .pdf (case insensitive), a
zero-padded page range, preceded by a dash, is inserted before the file
extension
* Otherwise, the file name is appended with a zero-padded page range
preceded by a dash.
Page ranges are single page numbers for single-page groups or first-last
for multipage groups.
Encryption Options
------------------
--encrypt user-password owner-password key-length flags --
Note that -- terminates parsing of encryption flags.
Either or both of the user password and the owner password may be
empty strings.
key-length may be 40, 128, or 256
Additional flags are dependent upon key length.
If 40:
--print=[yn] allow printing
--modify=[yn] allow document modification
--extract=[yn] allow text/graphic extraction
--annotate=[yn] allow comments and form fill-in and signing
If 128:
--accessibility=[yn] allow accessibility to visually impaired
--extract=[yn] allow other text/graphic extraction
--print=print-opt control printing access
--assemble=[yn] allow document assembly
--annotate=[yn] allow commenting/filling form fields
--form=[yn] allow filling form fields
--modify-other=[yn] allow other modifications
--modify=modify-opt control modify access (old way)
--cleartext-metadata prevents encryption of metadata
--use-aes=[yn] indicates whether to use AES encryption
--force-V4 forces use of V=4 encryption handler
If 256, options are the same as 128 with these exceptions:
--force-V4 this option is not available with 256-bit keys
--use-aes this option is always on with 256-bit keys
--force-R5 forces use of deprecated R=5 encryption
print-opt may be:
full allow full printing
low allow only low-resolution printing
none disallow printing
modify-opt may be:
all allow full document modification
annotate allow comment authoring and form operations
form allow form field fill-in and signing
assembly allow document assembly only
none allow no modifications
The default for each permission option is to be fully permissive. Please
refer to the manual for more details on the modify options.
Specifying cleartext-metadata forces the PDF version to at least 1.5.
Specifying use of AES forces the PDF version to at least 1.6. These
options are both off by default.
The --force-V4 flag forces the V=4 encryption handler introduced in PDF 1.5
to be used even if not otherwise needed. This option is primarily useful
for testing qpdf and has no other practical use.
Password Modes
----------------------
The --password-mode controls how qpdf interprets passwords supplied
cases, but you can fine-tune with this option.
bytes: use the password literally as supplied
hex-bytes: interpret the password as a hex-encoded byte string
unicode: interpret the password as a UTF-8 encoded string
auto: attempt to infer the encoding and adjust as needed
This is a complex topic. See the manual for a complete discussion.
Page Selection Options
----------------------
These options allow pages to be selected from one or more PDF files.
Whatever file is given as the primary input file is used as the
starting point, but its pages are replaced with pages as specified.
--keep-files-open=[yn]
--keep-files-open-threshold=count
--pages file [ --password=password ] [ page-range ] ... --
For each file that pages should be taken from, specify the file, a
password needed to open the file (if any), and a page range. The
password needs to be given only once per file. If any of the input
files are the same as the primary input file or the file used to copy
encryption parameters (if specified), you do not need to repeat the
password here. The same file can be repeated multiple times. The
filename "." may be used to refer to the current input file. All
non-page data (info, outlines, page numbers, etc. are taken from the
primary input file. To discard this, use --empty as the primary
input.
By default, when more than 200 distinct files are specified, qpdf will
close each file when not being referenced. With 200 files or fewer, all
files will be kept open at the same time. This behavior can be overridden
by specifying --keep-files-open=[yn]. Closing and opening files can have
very high overhead on certain file systems, especially networked file
systems. The threshold of 200 can be modified with
--keep-files-open-threshold
The page range is a set of numbers separated by commas, ranges of
numbers separated dashes, or combinations of those. The character
"z" represents the last page. A number preceded by an "r" indicates
to count from the end, so "r3-r1" would be the last three pages of the
document. Pages can appear in any order. Ranges can appear with a
high number followed by a low number, which causes the pages to appear in
reverse. Numbers may be repeated. A page range may be appended with :odd
to indicate odd pages in the selected range or :even to indicate even
pages.
If the page range is omitted, the range of 1-z is assumed. qpdf decides
that the page range is omitted if the range argument is either -- or a
valid file name and not a valid range.
The usual behavior of --pages is to add all pages from the first file,
then all pages from the second file, and so on. If the --collate option
is specified, then pages are collated instead. In other words, qpdf takes
the first page from the first file, the first page from the second file,
and so on until it runs out of files; then it takes the second page from
each file, etc. When a file runs out of pages, it is skipped until all
specified pages are taken from all files.
See the manual for examples and a discussion of additional subtleties.
Overlay and Underlay Options
-------------------------------
These options allow pages from another file to be overlaid or underlaid
on the primary output. Overlaid pages are drawn on top of the destination
page and may obscure the page. Underlaid pages are drawn below the
destination page.
{--overlay | --underlay } file
[ --password=password ]
[ --to=page-range ]
[ --from=[page-range] ]
[ --repeat=page-range ]
--
For overlay and underlay, a file and optional password are specified, along
with a series of optional page ranges. The default behavior is that each
page of the overlay or underlay file is imposed on the corresponding page
of the primary output until it runs out of pages, and any extra pages are
ignored. The page range options all take page ranges in the same form as
the --pages option. They have the following meanings:
--to: the pages in the primary output to which overlay/underlay is
applied
--from: the pages from the overlay/underlay file that are used
--repeat: pages from the overlay/underlay that are repeated after
any "from" pages have been exhausted
Advanced Parsing Options
-------------------------------
These options control aspects of how qpdf reads PDF files. Mostly these are
of use to people who are working with damaged files. There is little reason
to use these options unless you are trying to solve specific problems.
--suppress-recovery prevents qpdf from attempting to recover damaged files
--ignore-xref-streams tells qpdf to ignore any cross-reference streams
Advanced Transformation Options
-------------------------------
These transformation options control fine points of how qpdf creates
the output file. Mostly these are of use only to people who are very
familiar with the PDF file format or who are PDF developers.
--stream-data=option controls transformation of stream data (below)
--compress-streams=[yn] controls whether to compress streams on output
--decode-level=option controls how to filter streams from the input
--recompress-flate recompress streams already compressed with Flate
--compression-level=n set zlib compression level; most effective with
--recompress-flate --object-streams=generate
--normalize-content=[yn] enables or disables normalization of content streams
--object-streams=mode controls handing of object streams
--preserve-unreferenced preserve unreferenced objects
--remove-unreferenced-resources={auto,yes,no}
whether to remove unreferenced page resources
--preserve-unreferenced-resources
synonym for --remove-unreferenced-resources=no
--newline-before-endstream always put a newline before endstream
--flatten-annotations=option
incorporate rendering of annotations into page
contents including those for interactive form
fields; may also want --generate-appearances
--generate-appearances generate appearance streams for form fields
--optimize-images compress images with DCT (JPEG) when advantageous
--oi-min-width=w do not optimize images whose width is below w;
default is 128. Use 0 to mean no minimum
--oi-min-height=h do not optimize images whose height is below h
default is 128. Use 0 to mean no minimum
--oi-min-area=a do not optimize images whose pixel count is below a
default is 16,384. Use 0 to mean no minimum
--externalize-inline-images convert inline images to regular images; by
default, images of at least 1,024 bytes are
externalized
--ii-min-bytes=bytes specify minimum size of inline images to be
converted to regular images
--keep-inline-images exclude inline images from image optimization
--remove-page-labels remove any page labels present in the output file
--qdf turns on "QDF mode" (below)
--linearize-pass1=file write intermediate pass of linearized file
for debugging
--min-version=version sets the minimum PDF version of the output file
--force-version=version forces this to be the PDF version of the output file
Options for --flatten-annotations are all, print, or screen. If the option
is print, only annotations marked as print are included. If the option is
screen, options marked as "no view" are excluded. Otherwise, annotations
are flattened regardless of the presence of print or NoView flags. It is
common for PDF files to have a flag set that appearance streams need to be
regenerated. This happens when someone changes a form value with software
that does not know how to render the new value. qpdf will not flatten form
fields in files like this. If you get this warning, you have two choices:
regenerate appearances, or use some other tool to generate the appearances.
qpdf does a pretty good job with most forms when only ASCII and "Windows
ANSI" characters are used in form field values, but if your form fields
contain other characters, rich text, or are other than left justified, you
will get better results first saving with other software.
Version numbers may be expressed as major.minor.extension-level, so 1.7.3
means PDF version 1.7 at extension level 3.
Values for stream data options:
compress recompress stream data when possible (default)
preserve leave all stream data as is
uncompress uncompress stream data when possible
Values for object stream mode:
preserve preserve original object streams (default)
generate use object streams wherever possible
When --compress-streams=n is specified, this overrides the default behavior
of qpdf, which is to attempt compress uncompressed streams. Setting
stream data mode to uncompress or preserve has the same effect.
The --decode-level parameter may be set to one of the following values:
none do not decode streams
generalized decode streams compressed with generalized filters
including LZW, Flate, and the ASCII encoding filters.
specialized additionally decode streams with non-lossy specialized
filters including RunLength
all additionally decode streams with lossy filters
including DCT (JPEG)
In qdf mode, by default, content normalization is turned on, and the
stream data mode is set to uncompress. QDF mode does not support
linearized files. The --linearize flag disables qdf mode.
Setting the minimum PDF version of the output file may raise the version
but will never lower it. Forcing the PDF version of the output file may
contents. You should only do this if you have no other possible way to
features not supported later versions.
Testing, Inspection, and Debugging Options
------------------------------------------
These options can be useful for digging into PDF files or for use in
automated test suites for software that uses the qpdf library.
--deterministic-id generate deterministic /ID
--static-id generate static /ID: FOR TESTING ONLY!
--static-aes-iv use a static initialization vector for AES-CBC
This is option is not secure! FOR TESTING ONLY!
--no-original-object-ids suppress original object ID comments in qdf mode
--show-encryption quickly show encryption parameters
--show-encryption-key when showing encryption, reveal the actual key
--check-linearization check file integrity and linearization status
--show-linearization check and show all linearization data
--show-xref show the contents of the cross-reference table
--show-object=trailer|obj[,gen]
show the contents of the given object
--raw-stream-data show raw stream data instead of object contents
--filtered-stream-data show filtered stream data instead of object contents
--show-npages print the number of pages in the file
--show-pages shows the object/generation number for each page
--with-images also shows the object IDs for images on each page
--check check file structure + encryption, linearization
--json generate a json representation of the file
--json-help describe the format of the json representation
--json-key=key repeatable; prune json structure to include only
specified keys. If absent, all keys are shown
--json-object=trailer|[obj,gen]
repeatable; include only specified objects in the
"objects" section of the json. If absent, all
objects are shown
The json representation generated by qpdf is designed to facilitate
processing of qpdf from other programming languages that have a hard
time calling C++ APIs. Run qpdf --json-help for details on the format.
The manual has more in-depth information about the json representation
and certain compatibility guarantees that qpdf provides.
The --raw-stream-data and --filtered-stream-data options are ignored
unless --show-object is given. Either of these options will cause the
stream data to be written to standard output.
If --filtered-stream-data is given and --normalize-content=y is also
given, qpdf will attempt to normalize the stream data as if it is a
page content stream. This attempt will be made even if it is not a
page content stream, in which case it will produce unusable results.
Ordinarily, qpdf exits with a status of 0 on success or a status of 2
if any errors occurred. If there were warnings but not errors, qpdf
exits with a status of 3. If warnings would have been issued but --no-warn
was given, an exit status of 3 is still used. If you want qpdf to exit
with status 0 when there are warnings, use the --warning-exit-0 flag.
When --no-warn and --warning-exit-0 are used together, the effect is for
qpdf to completely ignore warnings. qpdf does not use exit status 1,