Skip to content

Latest commit

 

History

History
3922 lines (2874 loc) · 151 KB

cli.rst

File metadata and controls

3922 lines (2874 loc) · 151 KB
Raw

Running qpdf

This chapter describes how to run the qpdf program from the command line.

Basic Invocation

Usage: qpdf [infile] [options] [outfile]

The qpdf command reads the PDF file {infile}, applies various transformations or modifications to the file in memory, and writes the result to {outfile}. When run with no options, the output file is functionally identical to the input file but may be structurally reorganized, and orphaned objects are removed from the file. Many options are available for applying transformations or modifications to the file.

{infile} can be a regular file, or it can be :qpdf--empty to start with an empty PDF file. There is no way to use standard input since the input file has to be seekable.

{outfile} can be a regular file, - to represent standard output, or :qpdf--replace-input to indicate that the input file should be overwritten. The output file does not have to be seekable, even when generating linearized files. You can also use :qpdf--split-pages to create separate output files for each page (or group of pages) instead of a single output file.

Password-protected files may be opened by specifying a password with :qpdf--password.

All options other than help options (see help-options) require an input file. If inspection or JSON options (see inspection-options and json-options) or help options are given, an output file must not be given. Otherwise, an output file is required.

If @filename appears as a word anywhere in the command-line, it will be read line by line, and each line will be treated as a command-line argument. Leading and trailing whitespace is intentionally not removed from lines, which makes it possible to handle arguments that start or end with spaces. The @- option allows arguments to be read from standard input. This allows qpdf to be invoked with an arbitrary number of arbitrarily long arguments. It is also very useful for avoiding having to pass passwords on the command line, though see also :qpdf--password-file. Note that the @filename can't appear in the middle of an argument, so constructs such as --arg=@filename will not work. Instead, you would have to include the option and its parameter (e.g., --option=parameter) as a line in the filename file and just pass @filename on the command line.

Related Options

Exit Status

The exit status of qpdf may be interpreted as follows:

Exit Codes
0 no errors or warnings were found
1 not used
2 errors were found; the file was not processed
3 warnings were found without errors

Notes:

  • A PDF file may have problems that qpdf can't detect.
  • With the :qpdf--warning-exit-0 option, exit status 0 is used even if there are warnings.
  • qpdf does not exit with status 1 since the shell uses this exit code if it is unable to invoke the command.
  • If both errors and warnings were found, exit status 2 is used.
  • The :qpdf--is-encrypted and :qpdf--requires-password options use different exit codes. See their help for details.

Related Options

Shell Completion

qpdf provides its own completion support for zsh and bash. You can enable bash completion with eval $(qpdf --completion-bash) and zsh completion with eval $(qpdf --completion-zsh). If qpdf is not in your path, you should use an absolute path to qpdf in the above invocation. If you invoke it with a relative path, it will warn you, and the completion won't work if you're in a different directory.

qpdf will use argv[0] to figure out where its executable is. This may produce unwanted results in some cases, especially if you are trying to use completion with a copy of qpdf that is run directly out of the source tree or that is invoked with a wrapper script. You can specify a full path to the qpdf you want to use for completion in the QPDF_EXECUTABLE environment variable.

Related Options

Help/Information

Help options provide some information about qpdf itself. Help options are only valid as the first and only command-line argument.

Related Options

General Options

This section describes general options that control qpdf's behavior. They are not necessarily related to the specific operation that is being performed and may be used whether or not an output file is being created.

Related Options

Advanced Control Options

Advanced control options control qpdf's behavior in ways that would normally never be needed by a user but that may be useful to developers or people investigating problems with specific files.

Related Options

PDF Transformation

The options discussed in this section tell qpdf to apply transformations that change the structure of a PDF file without changing its content. Examples include creating linearized (web-optimized) files, adding or removing encryption, restructuring files for older viewers, and rewriting files for human inspection. See also modification-options.

Related Options

Page Ranges

Several qpdf command-line options use page ranges. This section describes the syntax of a page range.

  • A plain number indicates a page numbered from 1, so 1 represents the first page.
  • A number preceded by r counts from the end, so r1 is the last page, r2 is the second-to-last page, etc.
  • The letter z represents the last page and is the same as r1.
  • Page numbers may appear in any order separated by commas.
  • Two page numbers separated by dashes represents the inclusive range of pages from the first to the second. If the first number is higher than the second number, it is the range of pages in reverse.
  • A number or dash-separated range of numbers may be prepended with x (from qpdf 11.7.1). This means to exclude the pages in that range from the previous range that didn't start with x.
  • The range may be appended with :odd or :even to select only pages from the resulting range in odd or even positions. In this case, odd and even refer to positions in the final range, not whether the original page number is odd or even.
Example Page Ranges
1,6,4 pages 1, 6, and 4 in that order
3-7 pages 3 through 7 inclusive in increasing order
7-3 pages 7, 6, 5, 4, and 3 in that order
1-z all pages in order
z-1 all pages in reverse order
1,3,5-9,15-12 pages 1, 3, 5, 6, 7, 8, 9, 15, 14, 13, and 12 in that order
r3-r1 the last three pages of the document
r1-r3 the last three pages of the document in reverse order
1-20:even even pages from 2 to 20
5,7-9,12 pages 5, 7, 8, 9, and 12
5,7-9,12:odd pages 5, 8, and 12, which are the pages in odd positions from the original set of 5, 7, 8, 9, 12
5,7-9,12:even pages 7 and 9, which are the pages in even positions from the original set of 5, 7, 8, 9, 12
1-10,x3-4 pages 1 through 10 except pages 3 and 4 (1, 2, and 5 through 10)
4-10,x7-9,12-8,xr5 In a 15-page file, this is 4, 5, 6, 10, 12, 10, 9, and 8 in that order. That is pages 4 through 10 except 7 through 9 followed by 12 through 8 descending except 11 (the fifth page from the end)

PDF Modification

Modification options make systematic changes to certain parts of the PDF, causing the PDF to render differently from the original. See also transformation-options.

Related Options

Encryption

This section describes the options used to create encrypted files. For other options related to encryption, see also :qpdf--decrypt and :qpdf--copy-encryption. For a more in-depth technical discussion of how PDF encryption works internally, see pdf-encryption.

To create an encrypted file, use one of

--encrypt \
  [--user-password=user-password] \
  [--owner-password=owner-password] \
  --bits=key-length [options] --

OR

--encrypt user-password owner-password key-length [options] --

The first form, with flags for the passwords and bit length, was introduced in qpdf 11.7.0. Only the :qpdf--bits option is is mandatory. This form allows you to use any text as the password. If passwords are specified, they must be given before the :qpdf--bits option.

The second form has been in qpdf since the beginning and wil continue to be supported. Either or both of user-password and owner-password may be empty strings.

The key-length parameter must be either 40, 128, or 256. The user and/or owner password may be omitted. Omitting either password enables the PDF file to be opened without a password. Specifying the same value for the user and owner password and specifying an empty owner password are both considered insecure.

Encryption options are terminated by -- by itself.

40-bit encryption is insecure, as is 128-bit encryption without AES. Use 256-bit encryption unless you have a specific reason to use an insecure format, such as testing or compatibility with very old viewers. You must use the :qpdf--allow-weak-crypto flag to create encrypted files that use insecure cryptographic algorithms. The :qpdf--allow-weak-crypto flag appears outside of --encrypt ... -- (before --encrypt or after --).

If {key-length} is 256, the minimum PDF version is 1.7 with extension level 8, and the AES-based encryption format used is the one described in the PDF 2.0 specification. Using 128-bit encryption forces the PDF version to be at least 1.4, or if AES is used, 1.6. Using 40-bit encryption forces the PDF version to be at least 1.3.

When 256-bit encryption is used, PDF files with empty owner passwords are insecure. To create such files, you must specify the :qpdf--allow-insecure option.

Available options vary by key length. Not all readers respect all restrictions. The default for each permission option is to be fully permissive. These restrictions may or may not be enforced by any particular reader. qpdf allows very granular setting of restrictions. Some readers may not recognize the combination of options you specify. If you specify certain combinations of restrictions and find a reader that doesn't seem to honor them as you expect, it is most likely not a bug in qpdf. qpdf itself does not obey encryption restrictions already imposed on the file. Doing so would be meaningless since qpdf can be used to remove encryption from the file entirely.

Here is a summary of encryption options. Details are provided in the help for each option.

Options for 40-bit Encryption Only
--annotate=[y|n] restrict comments, filling forms, and signing
--extract=[y|n] restrict text/graphic extraction
--modify=[y|n] restrict document modification
--print=[y|n] restrict printing
Options for 128-bit or 256-bit Encryption
--accessibility=[y|n] restrict accessibility (usually ignored)
--annotate=[y|n] restrict commenting/filling form fields
--assemble=[y|n] restrict document assembly
--extract=[y|n] restrict text/graphic extraction
--form=[y|n] restrict filling form fields
--modify-other=[y|n] restrict other modifications
--modify=modify-opt control modify access by level
--print=print-opt control printing access
--cleartext-metadata prevent encryption of metadata
Options for 128-bit Encryption Only
--use-aes=[y|n] indicates whether to use AES encryption
--force-V4 forces use of V=4 encryption handler
Options for 256-bit Encryption Only
--force-R5 forces use of deprecated R=5 encryption algorithm
--allow-insecure allow user password with empty owner password
Values for {print-opt}
none disallow printing
low allow only low-resolution printing
full allow full printing
Values for {modify-opt}
none allow no modifications
assembly allow document assembly only
form assembly permissions plus filling in form fields and signing
annotate form permissions plus commenting and modifying forms
all allow full document modification

Related Options

Page Selection

qpdf allows you to use the :qpdf--pages option to split and merge PDF files by selecting pages from one or more input files.

qpdf primary-input.pdf \
  --pages \
  --file=input.pdf \
  [--range=page-range] \
  [--password=password] \
  [...] \
  -- output.pdf

OR

qpdf primary-input.pdf \
  --pages \
  input.pdf [--password=password] [page-range] \
  [...] -- output.pdf
Notes:
  • The first form, with :qpdf--file and :qpdf--range, was introduced in qpdf 11.9.0. In this form, the :qpdf--range and :qpdf--password options apply to the most recently specified :qpdf--file option.
  • The password option is needed only for password-protected files. If you specify the same file more than once, you only need to supply the password the first time.
  • The page range may be omitted. If omitted, all pages are included.
  • Document-level information, such as outlines, tags, etc., is taken from the primary input file (in the above example, in.pdf) and is preserved in out.pdf. You can use :qpdf--empty in place of an input file to start from an empty file and just copy pages equally from all files.
  • You can use . as a shorthand for the primary input file, if not empty.

See page-ranges for help on specifying a page range.

Use --collate={n} to cause pages to be collated in groups of {n} pages (default 1) instead of concatenating the input. Use --collate={i},{j},{k},... to take {i} from the first, then {j} from the second, then {k} from the third, then {i} from the first, etc.

Note that the :qpdf--collate appears outside of --pages ... -- (before --pages or after --). Pages are pulled from each document in turn. When a document is out of pages, it is skipped. See examples below.

Examples

  • Start with in.pdf and append all pages from a.pdf and the even pages from b.pdf, and write the output to out.pdf. Document-level information from in.pdf is retained. Note the use of . to refer to in.pdf.

    qpdf in.pdf --pages . a.pdf b.pdf 1-z:even -- out.pdf

  • Take all the pages from a.pdf, all the pages from b.pdf in reverse, and only pages 3 and 6 from c.pdf and write the result to out.pdf. Document-level metadata is discarded from all input files. The password x is used to open b.pdf.

    qpdf --empty --pages --file=a.pdf \
  --file=b.pdf --password=x --range=z-1 \
  --file=c.pdf --range=3,6 -- out.pdf

  • Scan a document with double-sided printing by scanning the fronts into odd.pdf and the backs into even.pdf. Collate the results into all.pdf. This takes the first page of odd.pdf, the first page of even.pdf, the second page of odd.pdf, the second page of even.pdf, etc.

    qpdf --collate odd.pdf --pages . even.pdf -- all.pdf
  OR
qpdf --collate --empty --pages odd.pdf even.pdf -- all.pdf
  OR
qpdf --collate --empty --pages --file=odd.pdf --file=even.pdf -- all.pdf

  • When collating, any number of files and page ranges can be specified. If any file has fewer pages, that file is just skipped when its pages have all been included. For example, if you ran

    qpdf --collate --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf r1 -- out.pdf

    you would get the following pages in this order:

    • a.pdf page 1
    • b.pdf page 6
    • c.pdf last page
    • a.pdf page 2
    • b.pdf page 5
    • a.pdf page 3
    • b.pdf page 4
    • a.pdf page 4
    • a.pdf page 5

  • You can specify a numeric parameter to :qpdf--collate. With --collate={n}, pull groups of {n} pages from each file, as always, stopping when there are no more pages. For example, if you ran

    qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf r1 -- out.pdf

    you would get the following pages in this order:

    • a.pdf page 1
    • a.pdf page 2
    • b.pdf page 6
    • b.pdf page 5
    • c.pdf last page
    • a.pdf page 3
    • a.pdf page 4
    • b.pdf page 4
    • a.pdf page 5

  • You can specify a multiple numeric parameters to :qpdf--collate. With --collate={i,j,k}, pull groups of {i} pages from the first file, then {j} from the second, then {k} from the third, repeating. The number of parameters must equal the number of groups. For example, if you ran

    qpdf --collate=2,1,3 --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf r1-r4 -- out.pdf

    you would get the following pages in this order:

    • a.pdf pages 1 and 2
    • b.pdf page 6
    • c.pdf last three pages in reverse order
    • a.pdf pages 3 and 4
    • b.pdf page 5
    • c.pdf fourth to last page
    • a.pdf page 5
    • b.pdf page 4

  • Take pages 1 through 5 from file1.pdf and pages 11 through 15 in reverse from file2.pdf, taking document-level metadata from file2.pdf.

    qpdf file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf

  • Here's a more contrived example. If, for some reason, you wanted to take the first page of an encrypted file called encrypted.pdf with password pass and repeat it twice in an output file without any shared data between the two copies of page 1, and if you wanted to drop document-level metadata but preserve encryption, you could run

    qpdf --empty --copy-encryption=encrypted.pdf \
     --encryption-file-password=pass \
     --pages encrypted.pdf --password=pass 1 \
           ./encrypted.pdf --password=pass 1 -- \
     outfile.pdf

    Note that we had to specify the password all three times because giving a password as :qpdf--encryption-file-password doesn't count for page selection, and as far as qpdf is concerned, encrypted.pdf and ./encrypted.pdf are separate files. (This is by design. See page-limitations for a discussion.) These are all corner cases that most users should hopefully never have to be bothered with.

Limitations

With the exception of page labels (page numbers), qpdf doesn't yet have full support for handling document-level data as it relates to pages. Certain document-level features such as form fields, outlines (bookmarks), and article tags among others, are copied in their entirety from the primary input file. Starting with qpdf version 8.3, page labels are preserved from all files unless :qpdf--remove-page-labels is specified.

It is expected that a future version of qpdf will have more complete and configurable behavior regarding document-level metadata. In the meantime, semantics of splitting and merging vary across features. For example, the document's outlines (bookmarks) point to actual page objects, so if you select some pages and not others, bookmarks that point to pages that are in the output file will work, and remaining bookmarks will not work. If you don't want to preserve the primary file's metadata, use :qpdf--empty as the primary input file.

Visit qpdf issues labeled with "pages" or look at the TODO file in the qpdf source distribution for some of the ideas.

Prior to qpdf version 8.4, it was not possible to specify the same page from the same file directly more than once, and a workaround of specifying the same file in more than one way was required. Version 8.4 removes this limitation, but when the same page is copied more than once, all its data is shared between the pages. Sometimes this is fine, but sometimes it may not work correctly, particularly if there are form fields or you intend to perform other modifications on one of the pages. A future version of qpdf should address this more completely. You can work around this by specifying the same file in two different ways. For example qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf would create a file with two copies of the first page of the input, and the two copies would not share any objects in common. This includes fonts, images, and anything else the page references.

Overlay and Underlay

You can use qpdf to overlay or underlay pages from other files onto the output generated by qpdf. Specify overlay or underlay as follows:

{--overlay|--underlay} [--file=]file [options] --

Overlay and underlay options are processed late, so they can be combined with other options like merging and will apply to the final output. The --overlay and --underlay options work the same way, except underlay pages are drawn underneath the page to which they are applied, possibly obscured by the original page, and overlay files are drawn on top of the page to which they are applied, possibly obscuring the page. The ability to specify the file using the :qpdf--file option was added in qpdf 11.9.0. You can combine overlay and underlay. Starting in qpdf 11.9.0, you can specify these options multiple times. The final page will be a stack containing the underlays in order of appearance, then the original page, then the overlays in order of appearance.

The default behavior of overlay and underlay is that pages are taken from the overlay/underlay file in sequence and applied to corresponding pages in the output until there are no more output pages. If the overlay or underlay file runs out of pages, remaining output pages are left alone. This behavior can be modified by options, which are provided between the --overlay or --underlay flag and the -- option. The following options are supported:

Specify a page range (see page-ranges) that indicates which pages in the output should have the overlay/underlay applied. If not specified, overlay/underlay are applied to all pages.

Specify a page range that indicates which pages in the overlay/underlay file will be used for overlay or underlay. If not specified, all pages will be used. The "from" pages are used until they are exhausted, after which any pages specified with :qpdf--repeat are used. If you are using the :qpdf--repeat option, you can use --from= to provide an empty set of "from" pages.

Specify an optional page range that indicates which pages in the overlay/underlay file will be repeated after the "from" pages are used up. If you want to apply a repeat a range of pages starting with the first page of output, you can explicitly use --from=.

Examples

  • Overlay the first three pages from file o.pdf onto the first three pages of the output, then overlay page 4 from o.pdf onto pages 4 and 5 of the output. Leave remaining output pages untouched.

    qpdf in.pdf --overlay o.pdf --to=1-5 --from=1-3 --repeat=4 -- out.pdf

  • Underlay page 1 of footer.pdf on all odd output pages, and underlay page 2 of footer.pdf on all even output pages.

    qpdf in.pdf --underlay footer.pdf --from= --repeat=1,2 -- out.pdf

  • Combine two files and overlay the single page from watermark.pdf on the result.

    qpdf --empty --pages a.pdf b.pdf -- \
     --overlay watermark.pdf --from= --repeat=1 -- out.pdf

Embedded Files/Attachments

It is possible to list, add, or delete embedded files (also known as attachments) and to copy attachments from other files. See also :qpdf--list-attachments and :qpdf--show-attachment.

Related Options

PDF Date Format

When a date is required, the date should conform to the PDF date format specification, which is D:{yyyymmddhhmmssz} where {z} is either literally upper case Z for UTC or a timezone offset in the form {-hh'mm'} or {+hh'mm'}. Negative timezone offsets indicate time before UTC. Positive offsets indicate how far after. For example, US Eastern Standard Time (America/New_York) is -05'00', and Indian Standard Time (Asia/Calcutta) is +05'30'.

PDF Date Examples
D:20210207161528-05'00' February 7, 2021 at 4:15:28 p.m.
D:20210207211528Z February 7, 2021 at 21:15:28 UTC

Options for Adding Attachments

These options are valid between :qpdf--add-attachment and --.

Options for Copying Attachments

Options in this section are valid between :qpdf--copy-attachments-from and --.

PDF Inspection

These options provide tools for inspecting PDF files. When any of the options in this section are specified, no output file may be given.

Related Options

JSON Options

It is possible to view information about PDF files in a JSON format. See json for details about the qpdf JSON format.

Related Options

Options for Testing or Debugging

The options below are useful when writing automated test code that includes files created by qpdf or when testing qpdf itself. When changes are made to qpdf, care is taken to avoid gratuitously changing the output of PDF files. This is to make it easier to do direct comparisons in test suites with files created by qpdf. However, there are no guarantees that the PDF output won't change such as in the event of a bug fix or feature enhancement to some aspect of the output that qpdf creates.

Idempotency

Note about idempotency of byte-for-byte content: there is no expectation that qpdf is idempotent in the general case. In other words, there is no expectation that, when qpdf is run on its own output, it will create byte-for-byte identical output, even though it will create semantically identical files. There are a variety of reasons for this including document ID generation, which includes a random element, as well as the interaction of stream length encoding with dictionary key sorting.

It is possible to get idempotent behavior by using the :qpdf--deterministic-id (or, for testing only, :qpdf--static-id) option with qpdf and running it three times so that you are processing the output of qpdf on its own previous output. For example, in this sequence of commands:

qpdf any-file.pdf 1.pdf
qpdf --deterministic-id 1.pdf 2.pdf
qpdf --deterministic-id 2.pdf 3.pdf

the files 2.pdf and 3.pdf should be byte-for-byte identical. The qpdf test suite relies on this behavior. See also :qpdf--static-aes-iv, which should also be used only for testing.

Related Options

Unicode Passwords

At the library API level, all methods that perform encryption and decryption interpret passwords as strings of bytes. It is up to the caller to ensure that they are appropriately encoded. Starting with qpdf version 8.4.0, qpdf will attempt to make this easier for you when interacting with qpdf via its command line interface. The PDF specification requires passwords used to encrypt files with 40-bit or 128-bit encryption to be encoded with PDF Doc encoding. This encoding is a single-byte encoding that supports ISO-Latin-1 and a handful of other commonly used characters. It has a large overlap with Windows ANSI but is not exactly the same. There is generally no way to provide PDF Doc encoded strings on the command line. As such, qpdf versions prior to 8.4.0 would often create PDF files that couldn't be opened with other software when given a password with non-ASCII characters to encrypt a file with 40-bit or 128-bit encryption. Starting with qpdf 8.4.0, qpdf recognizes the encoding of the parameter and transcodes it as needed. The rest of this section provides the details about exactly how qpdf behaves. Most users will not need to know this information, but it might be useful if you have been working around qpdf's old behavior or if you are using qpdf to generate encrypted files for testing other PDF software.

A note about Windows: when qpdf builds, it attempts to determine what it has to do to use wmain instead of main on Windows. The wmain function is an alternative entry point that receives all arguments as UTF-16-encoded strings. When qpdf starts up this way, it converts all the strings to UTF-8 encoding and then invokes the regular main. This means that, as far as qpdf is concerned, it receives its command-line arguments with UTF-8 encoding, just as it would in any modern Linux or UNIX environment.

If a file is being encrypted with 40-bit or 128-bit encryption and the supplied password is not a valid UTF-8 string, qpdf will fall back to the behavior of interpreting the password as a string of bytes. If you have old scripts that encrypt files by passing the output of iconv to qpdf, you no longer need to do that, but if you do, qpdf should still work. The only exception would be for the extremely unlikely case of a password that is encoded with a single-byte encoding but also happens to be valid UTF-8. Such a password would contain strings of even numbers of characters that alternate between accented letters and symbols. In the extremely unlikely event that you are intentionally using such passwords and qpdf is thwarting you by interpreting them as UTF-8, you can use --password-mode=bytes to suppress qpdf's automatic behavior.

The :qpdf--password-mode option, as described earlier in this chapter, can be used to change qpdf's interpretation of supplied passwords. There are very few reasons to use this option. One would be the unlikely case described in the previous paragraph in which the supplied password happens to be valid UTF-8 but isn't supposed to be UTF-8. Your best bet would be just to provide the password as a valid UTF-8 string, but you could also use --password-mode=bytes. Another reason to use --password-mode=bytes would be to intentionally generate PDF files encrypted with passwords that are not properly encoded. The qpdf test suite does this to generate invalid files for the purpose of testing its password recovery capability. If you were trying to create intentionally incorrect files for a similar purposes, the bytes password mode can enable you to do this.

When qpdf attempts to decrypt a file with a password that contains non-ASCII characters, it will generate a list of alternative passwords by attempting to interpret the password as each of a handful of different coding systems and then transcode them to the required format. This helps to compensate for the supplied password being given in the wrong coding system, such as would happen if you used the iconv workaround that was previously needed. It also generates passwords by doing the reverse operation: translating from correct in incorrect encoding of the password. This would enable qpdf to decrypt files using passwords that were improperly encoded by whatever software encrypted the files, including older versions of qpdf invoked without properly encoded passwords. The combination of these two recovery methods should make qpdf transparently open most encrypted files with the password supplied correctly but in the wrong coding system. There are no real downsides to this behavior, but if you don't want qpdf to do this, you can use the :qpdf--suppress-password-recovery option. One reason to do that is to ensure that you know the exact password that was used to encrypt the file.

With these changes, qpdf now generates compliant passwords in most cases. There are still some exceptions. In particular, the PDF specification directs compliant writers to normalize Unicode passwords and to perform certain transformations on passwords with bidirectional text. Implementing this functionality requires using a real Unicode library like ICU. If a client application that uses qpdf wants to do this, the qpdf library will accept the resulting passwords, but qpdf will not perform these transformations itself. It is possible that this will be addressed in a future version of qpdf. The QPDFWriter methods that enable encryption on the output file accept passwords as strings of bytes.

Please note that the :qpdf--password-is-hex-key option is unrelated to all this. That flag bypasses the normal process of going from password to encryption key entirely, allowing the raw encryption key to be specified directly. That behavior is useful for forensic purposes or for brute-force recovery of files with unknown passwords and has nothing to do with the document's actual passwords.