How to Use qpdf: The Beginner's Guide (First Merge, the --empty Lesson, Decryption, Page Ranges, and the Linearize Arc)

CodexFuse Team · 2026-11-07T05:03:46.721Z · 20 min read min read

How Do I Use qpdf?

Learning how to use qpdf takes seven moves: install qpdf 12.4.2, check the version, merge two PDFs with --empty --pages, extract a page range, rotate a page, decrypt a locked file you own, and linearize the result for the web. qpdf is a free, open-source command-line tool that performs content-preserving transformations on PDF files, and it runs on Linux, macOS, and Windows. This qpdf tutorial follows the official documentation, the project repository, and the release notes, with every fact checked as of November 2026.

qpdf here means the C++ command-line tool from qpdf/qpdf, not the unrelated QuantumPDF package that shares its name on PyPI. CodexFuse offers no qpdf tool, so this guide teaches the real project on your own machine, not a web version of it. No Facebook promotion applies to this guide.

The single biggest trap for beginners is the search results themselves, which rank man pages and a stale docs chapter above any real guide. If you want a point-and-click PDF toolkit instead of a terminal, the Stirling-PDF beginner guide covers the web GUI lane, while this guide covers the command line. The two lanes never rival each other, because one is a browser app and the other is a scriptable tool.

1. Install qpdf from your package manager and run qpdf --version to confirm 12.4.2.
2. Merge two PDFs with qpdf --empty --pages first.pdf second.pdf -- combined.pdf.
3. Extract pages with a range such as 1-3,7,11,18-21,55.
4. Rotate pages with --rotate=+90 on the pages you need.
5. Decrypt a file you own with --decrypt and the password that opens it.
6. Encrypt the result with --encrypt and 256-bit keys when it must stay private.
7. Linearize the finished file with --linearize so readers can open it before the download ends.

What Is qpdf, Exactly?

qpdf is a command-line tool and C++ library that performs content-preserving transformations on PDF files. It supports linearization, encryption, and numerous other features, and it can split and merge files, create PDF files from content you supply yourself, and inspect files for study or analysis. qpdf does not render PDFs or perform text extraction, and it holds no higher-level interface for working with page contents.

The project started on 3 June 2012, so it is 5,270 days old, or 14.43 years, as of 7 November 2026. The repository carries 5,563 stars and 417 forks, which is 13.34 stars per fork, and 189 open issues, or 3.40 open issues per 100 stars. The current release is 12.4.2, published 27 September 2026, which is 41 days ago, and the last push landed 42 days ago.

from datetime import date
today = date(2026, 11, 7)
qpdf_created = date(2012, 6, 3)
qpdf_release = date(2026, 9, 27)
qpdf_push = date(2026, 9, 26)
cpu_created = date(2017, 6, 18)
cpu_push = date(2026, 11, 2)
split_article = date(2022, 9, 19)
print((today - qpdf_created).days)
print(round((today - qpdf_created).days / 365.25, 2))
print(round(5563 / 417, 2))
print(round(189 / 5563 * 100, 2))
print((today - qpdf_release).days)
print((today - qpdf_push).days)
print((today - cpu_created).days)
print(round((today - cpu_created).days / 365.25, 2))
print(round(8895 / 644, 2))
print(round(111 / 8895 * 100, 2))
print((today - cpu_push).days)
print(round(5563 / 8895, 2))
print((today - qpdf_created).days - (today - cpu_created).days)
print(round(10461 / 30, 1))
print((today - split_article).days)

A roundup of PDF statistics for 2026 puts the format in context, and qpdf sits in the middle of that world as the scriptable half of the PDF toolkit. Every number in this guide comes from a source fetched on 7 November 2026, and the computed block above shows the arithmetic behind the figures in this section.

Why Is There No Single Beginner Guide for qpdf?

A live check of Google page 1 for how to use qpdf on 7 November 2026 returns Debian and Arch man pages, a ManKier copy, and the official Running qpdf chapter. The search index still serves the 11.8 docs chapter, even though the stable docs are 12.4.2, so the top documentation hit is four minor versions behind. No independent article and no tool page ranks for the query at all.

The qpdf tutorial query is thinner still: a quantum-computing tutorial with a similar name, a dev.to guide updated 5 days ago that covers only splitting, two WebAssembly app builds, and a vendor C++ page. The closest thing to a general guide is a combine-PDFs article the search index dates about 1,510 days back, which is roughly 19 September 2022. That gap is why this guide exists: install, merge, split, rotate, encrypt, decrypt, linearize, and inspect in one place, pinned to 12.4.2.

How Do I Install qpdf?

Install qpdf from your system package manager, not from PyPI. pip install qpdf installs an unrelated QuantumPDF tool, a desktop app that merely depends on pikepdf, and it never installs the qpdf command. The real Python binding is pikepdf 10.17.0, which describes itself as powered by qpdf.

sudo apt install qpdf
brew install qpdf
choco install qpdf
winget install --id=QPDF.QPDF -e
qpdf --version

Homebrew reports 10,461 installs and 241,750 downloads in the last 30 days, or 348.7 installs a day. Debian stable still ships 12.2.0-1, so apt users on trixie get an older qpdf than upstream, while testing and sid already carry 12.4.2-1. Ubuntu noble ships 11.9.0-1.1build1, which is older still.

After installing, run qpdf --version and confirm 12.4.2 before you follow any command in this guide. The macOS binaries are new in 12.4.2 and are not signed with an Apple Developer ID or notarized, so the README tells you to clear the quarantine attribute after unzipping. Releases are signed with cosign as well as GPG, and each release ships a checksum file.

xattr -r -d com.apple.quarantine bin lib

What Is the --empty Lesson?

The --empty lesson is the one idea that makes every qpdf command click: --empty means start with a zero-page PDF, not open a file called empty. Every merge, extract, and split command in this guide starts from that blank document and then copies pages into it with --pages. Once you see --empty as a blank starting point, the rest of the syntax reads plainly.

The alternative is to name a real file as the primary input, which keeps that file's document-level information, such as outlines and tags. The dot in qpdf in.pdf --pages . a.pdf b.pdf 1-z:even -- out.pdf is shorthand for the primary input file, so its pages stay first and its outlines survive. --empty copies pages equally from every file and keeps no document-level data from any of them, so pick the form that matches the job.

The double dash -- separates the page list from the output file, and qpdf needs it wherever --pages takes file names. Forgetting it is the most common syntax error in beginner commands, and qpdf answers with a usage error instead of a merged file. Treat -- as the period at the end of the page list.

How Do I Merge PDFs with qpdf?

The qpdf merge pdf pattern is one command: qpdf --empty --pages first.pdf second.pdf -- combined.pdf. The --pages list takes file names in order, and the -- before combined.pdf marks the end of that list. The output holds every page of first.pdf followed by every page of second.pdf, with the content copied, not re-rendered.

If you would rather merge in a browser, the merge PDF files online guide covers the hosted route, but the command line wins when the job repeats or runs on a server. Merging with qpdf never changes the visible content, because qpdf copies pages and objects instead of redrawing them. A server-side merge is also where a VPS hosting guide earns its keep, since the same command runs unchanged on a remote machine.

qpdf --empty --pages first.pdf second.pdf -- combined.pdf
qpdf --empty --pages *.pdf -- all.pdf
qpdf --empty --pages large.pdf 1-3,7,11,18-21,55 -- summary.pdf
qpdf in.pdf --pages . a.pdf b.pdf 1-z:even -- out.pdf

Page ranges follow a small grammar that is worth learning once. The table below lists the forms the docs define, and the same grammar works in every --pages command in this guide.

Two details catch beginners: :odd and :even count positions inside the range you wrote, not original page numbers, and a range such as 7-3 runs backward on purpose. The --collate option groups pages instead of concatenating them, which matters when you merge sets of pages that belong together. Test every range on a copy first, because qpdf writes a new file and leaves the inputs untouched.

How Do I Split Pages and Extract Ranges?

The qpdf split pdf pages command writes one file per page: qpdf --split-pages infile.pdf %d-out. A 12-page file becomes 01-out through 12-out, with the page number replacing %d. The grouped form qpdf --split-pages=2 infile.pdf outfile.pdf writes two-page files named outfile-01-02.pdf, outfile-03-04.pdf, and so on.

To pull a range into one file instead of many, use the merge pattern with a range: qpdf --empty --pages large.pdf 8-13 -- chapter2.pdf. A dev.to guide updated 5 days ago tests exactly this shape on a dummy 8-page statement with qpdf 12.4.2, using ranges such as 3-4, 2,5, 7-z, r2-r1, and 1-z,x5. If you would rather split in a browser, the split a PDF guide covers the hosted route for a one-off job.

--split-pages does not preserve outlines, threads, or other document-level features, because each output page is copied from a fresh empty PDF. That is the one caveat to remember before you split a file that readers navigate by bookmarks. To keep document-level data, run --pages once per page instead of splitting, which is slower but preserves the structure.

How Do I Rotate Pages with qpdf?

A qpdf rotate pdf command takes an angle and a page range: qpdf in.pdf out.pdf --rotate=+90:2,4,6. The plus sign adds the angle to the current rotation, so +90 turns the page 90 degrees clockwise, and -90 turns it 90 degrees counter-clockwise. An angle with no sign sets the absolute rotation instead, which the docs advise against for most jobs.

Only four angles exist: 0, 90, 180, and 270. The command qpdf in.pdf out.pdf --rotate=+180:7-8 turns pages 7 and 8 upside down, while --rotate=+180 alone turns every page, and --rotate=0 forces the natural orientation. The --flatten-rotation option bakes the rotation into the page content itself, which helps viewers that ignore the rotation flag.

qpdf in.pdf out.pdf --rotate=+90:2,4,6
qpdf in.pdf out.pdf --rotate=+180:7-8
qpdf in.pdf out.pdf --rotate=+180
qpdf in.pdf out.pdf --rotate=0

How Do I Decrypt and Encrypt PDFs?

A qpdf decrypt pdf job is the simplest command in this guide: qpdf --decrypt in.pdf out.pdf. The output file carries no encryption, even when the input was locked, and --decrypt overrides the default habit of preserving whatever encryption the input had. --decrypt is not a password cracker: a file with a user password still needs that password to open, through --password=your-password, and the command only works once the file can be opened.

The docs add that this feature is not meant for bypassing copyright restrictions or other limits a producer placed on a file. Passwords can also come from a file with --password-file, or from standard input, which keeps them out of the shell history. The --remove-restrictions option drops the security limits on a signed file, but it invalidates the signature, so use it only when that trade is acceptable.

qpdf --decrypt in.pdf out.pdf
qpdf --decrypt --password=your-password in.pdf out.pdf
qpdf --encrypt user-pass owner-pass 256 -- in.pdf out.pdf

A qpdf encrypt pdf command takes two passwords and a key length: qpdf --encrypt user-pass owner-pass 256 -- in.pdf out.pdf. The first password opens the file, the second controls permissions, and the key length is 40, 128, or 256 bits. Use 256-bit encryption unless you have a specific reason not to, because 40-bit and 128-bit keys without AES use RC4, which is insecure, and creating RC4 files since qpdf 11.0 needs the --allow-weak-crypto flag.

The newer form, available since 11.7.0, names each part: qpdf --encrypt --user-password=your-password --owner-password=your-password --bits=256 -- in.pdf out.pdf. Permission flags sit inside the --encrypt block, with --print=none, --modify=none, --annotate=n, --extract=n, --assemble=n, --form=n, and --accessibility=n each locking one ability. qpdf does not enforce the permission flags on a file it opens, because it can remove the encryption entirely, so treat permissions as a request to honest readers, not a lock.

How Do I Linearize a PDF for the Web?

A qpdf linearize run rewrites the file so compliant readers can start showing it before the whole download arrives. Ordinary PDFs keep their cross-reference information at the end of the file, so the reader must wait for the full download before it can render anything. Linearized files, also called web-optimized or fast-web-view files, move that information up front.

The command is one flag: qpdf --linearize in.pdf out.pdf. Release 12.4.2 made linearization far more memory-efficient for some files, and the release notes say the team has seen 30x improvements in some cases, with a small speed gain as well. The --check-linearization flag verifies the result, and --show-linearization prints the hint-table data, including the object numbers qpdf assigns to each part since 12.4.2.

Linearize the file you actually serve, not every file you own, because the rewrite costs a pass over the whole document. The flag disables QDF mode, so do not combine it with --qdf in one command. For a file that readers download once and keep, the gain is small, but for a file that hundreds of readers open in a browser, it is the cheapest speed win qpdf offers.

qpdf --linearize in.pdf out.pdf
qpdf --check-linearization out.pdf
qpdf --show-linearization out.pdf

How Do I Inspect a PDF with qpdf?

The qpdf json output is a machine-readable map of the file: qpdf --json in.pdf out.json. The default JSON version is 2, and the version key in the output says which one you got. The --json-output form changes the defaults so stream data comes inline and only the qpdf key is included, which suits scripts that parse one field.

Before you parse anything, run qpdf --check in.pdf, which reads the file structure, encryption, linearization, and stream encoding and reports problems to standard output. Exit code 0 means no errors or warnings, 2 means errors, and 3 means warnings only, while --warning-exit-0 turns warnings into a clean exit. Since 12.3.0, --check also covers AcroForm, Dests, Outlines, and PageLabels, so it catches more broken files than it used to.

The fastest page count in any script is qpdf --show-npages in.pdf, which prints one number on one line. The same family holds --show-encryption, --show-xref, --show-pages, and --list-attachments, each answering one question without opening the file in a viewer. Shell completion comes free since 12.4.0, through eval with qpdf --completion-bash or qpdf --completion-zsh.

qpdf --check in.pdf
qpdf --show-npages in.pdf
qpdf --json in.pdf out.json
qpdf --json-output in.pdf out.json

How Do I Shrink a PDF with qpdf?

A qpdf compress pdf job is a combination of four options, because there is no --compress flag in qpdf. The recipe that a Medium guide updated 5 days ago attests is qpdf input.pdf --object-streams=generate --stream-data=compress --recompress-flate --compression-level=9 output.pdf, and every flag in it exists in the 12.4.2 docs. The command squeezes object streams, recompresses flate streams, and raises the zlib level to 9, which is the smallest and slowest setting.

The --object-streams=generate flag creates object streams and usually shrinks the file the most, and it forces PDF 1.5 or later. The --compression-level flag takes 1 to 9 and passes the value to zlib, while --recompress-flate uncompresses and recompresses streams that were already flate, which is slower but lets the level setting reach them. The docs add that streams with more than 25 filters are treated as unfilterable by default, which protects the tool from damaged or hostile files.

qpdf input.pdf --object-streams=generate --stream-data=compress --recompress-flate --compression-level=9 output.pdf
qpdf input.pdf --object-streams=generate --optimize-images --jpeg-quality=80 output.pdf

The --optimize-images flag recompresses non-JPEG images as JPEG when it shrinks them, with --jpeg-quality taking 0 to 100 and a minimum image size of 128 by 128 pixels or 16,384 pixels of area. It does not downsample photos, so compare the before and after sizes instead of assuming the file shrank. A file that is mostly scanned images barely moves, while a file full of uncompressed streams is where the recipe earns its keep.

qpdf vs pdfcpu: What Changes If I Switch?

qpdf vs pdfcpu is the comparison most readers ask about, and the two tools overlap more than they differ. Both are Apache-2.0 command-line tools that split, merge, rotate, encrypt, decrypt, and validate PDFs, and both are free. The differences are age, language, and command style, not the job list.

qpdf is 1,841 days older than pdfcpu, and it holds 0.63 times as many stars, so pdfcpu is the more starred project while qpdf is the older one. pdfcpu states that it supports PDF versions through PDF 2.0, while qpdf makes no single version claim in the sources fetched for this guide. Pick qpdf when you need its JSON output, QDF mode, or linearization, and pick pdfcpu when you want its Go tooling or its stamp and watermark features.

Seven Mistakes Beginners Make with qpdf

Sources

The repository facts come from the GitHub API pages for qpdf/qpdf and pdfcpu/pdfcpu, fetched 7 November 2026, which list 5,563 stars, 417 forks, 189 open issues, a 3 June 2012 creation date, and a last push on 26 September 2026 for qpdf, and 8,895 stars, 644 forks, 111 open issues, an 18 June 2017 creation date, and a last push on 2 November 2026 for pdfcpu. The latest-release endpoint for qpdf/qpdf gives v12.4.2, published 27 September 2026, with new macOS, Windows arm64, and Linux aarch64 binaries and linearization that the release notes call vastly more memory-efficient. Every computed figure in this guide was re-computed in Python this run from those dates and counts.

The install routes, the --empty model, page ranges, split, rotate, decrypt, encrypt, linearize, JSON, check, and compress options come from the official stable 12.4.2 docs at qpdf.readthedocs.io, including the CLI, installation, and release-notes pages, all fetched 7 November 2026. The package versions come from the Homebrew formula for qpdf, the Debian package tracker, the Ubuntu noble package page, the Chocolatey API feed, and the winget package manifests, all fetched the same day. The PyPI checks for qpdf 0.2.0, described as QuantumPDF, and pikepdf 10.17.0, described as powered by qpdf, were fetched 7 November 2026.

The search intent comes from live Google page-1 checks for how to use qpdf and qpdf tutorial on 7 November 2026, which return man pages, the 11.8 docs chapter, a dev.to split guide updated 5 days ago, and a combine-PDFs article the search index dates about 1,510 days back. The compress recipe comes from a Medium guide updated 5 days ago, and the Ghostscript flag correction comes from the Ghostscript 10.02.0 docs. No terminal outputs in this guide were executed in a live testbed, and every command shown comes from the official docs.

Frequently Asked Questions

Is qpdf free?

Yes, qpdf is free and open source under the Apache License 2.0, and there is nothing to buy. You run it on your own machine, so the only costs are your hardware and time. The copyright holder is Jay Berkenbilt, and the code lives in the public qpdf/qpdf repository.

Does qpdf work on Windows?

Yes, qpdf works on Windows through Chocolatey, winget, or the official 12.4.2 binaries, which now include a Windows arm64 build. The same commands run on all three systems, so a script written on Linux works on Windows with the same flags. The macOS binaries are new in 12.4.2 and need the quarantine attribute cleared after unzipping, because they are not signed or notarized.

Can qpdf remove a password I do not know?

No. A user-password-protected file still needs its password before qpdf can open it, and --decrypt only writes an unencrypted copy after the file opens. The owner-password case is different in some tools, but this guide states no claim about it, because the official docs do not verify it, and if you lost the password to your own file, qpdf cannot recover it for you.

Does qpdf change how my PDF looks?

No. qpdf copies pages and objects without re-rendering them, so the visible content stays the same and only the file structure changes. A plain qpdf run with no options writes output that is functionally identical to the input, minus orphaned objects. The one visible exception is rotation, which changes the page orientation on purpose.

What is the difference between qpdf and pikepdf?

pikepdf is the Python binding for qpdf, version 10.17.0, and it describes itself as powered by qpdf. It lets Python programs call the same engine that the command line uses, while qpdf itself stays a terminal tool. Install pikepdf when you script in Python, and install qpdf when you work in a shell.