PDF Page Labels Explained

Open a scanned book in a PDF viewer and you will often see something odd: the viewer says page 1 of 340, but the page in front of you is the cover, and the page numbered "1" in the printed text is the twelfth sheet. Somewhere in between there are roman numerals. Page labels are the PDF feature that reconciles these two numbering systems — and their absence is why citing a page from a PDF is so often ambiguous.

Two numbering systems, always

Every PDF has physical page indices: 1, 2, 3, … n, in file order, with no gaps and no choice about it. That is what a viewer counts and what qpdf --pages 5-9 means.

Many documents also have printed page numbers, which are ink on the page and follow the conventions of publishing: unnumbered front cover, roman numerals for front matter, arabic numerals restarting at 1 for the body, sometimes a per-chapter restart, sometimes an appendix numbered A-1 onwards.

Page labels are the mapping between the two. They are stored in the document catalogue as a /PageLabels number tree — a list of ranges, each saying "from physical page n, number pages using style S, prefix P, starting at st".

What a label range looks like

Conceptually, a book might declare:

• From index 0: style none, prefix "Cover" — one unnumbered sheet
• From index 1: style lowercase roman, starting at 1 — i, ii, iii, iv …
• From index 13: style decimal, starting at 1 — 1, 2, 3 …
• From index 301: style decimal, prefix "A-", starting at 1 — A-1, A-2 …

The available styles are decimal (/D), uppercase roman (/R), lowercase roman (/r), uppercase letters (/A), and lowercase letters (/a), each optionally combined with an arbitrary text prefix. The letter styles wrap in the publishing convention: after Z comes AA, then BB.

That is the whole feature. It is small, it has been in the specification since PDF 1.3, and it is why a well-made scan shows "xiv (14 of 340)" in the page box instead of just "14".

Why they matter more than they look

Citation. If you cite "page 43" of a PDF and the reader's viewer is counting physical pages while you were reading printed ones, you are pointing at different pages. In academic and legal work this is a real problem, not a theoretical one — which is why the legal world invented Bates numbering rather than relying on either system.

Navigation. With correct labels, typing "43" into the viewer's page box takes you to printed page 43. Without them, it takes you to the forty-third sheet, which in a book with twelve pages of front matter is page 31 of the text.

Splitting and merging. When you cut a 500-page document into parts, the parts should ideally carry labels that reflect their origin, so part three still calls its first page 287. Almost no tool does this automatically.

Search results and deep links. Any system that returns "found on page N" is choosing a numbering system, usually without saying which.

Seeing the labels in a file

Quick inspection routes:

• In a viewer: Acrobat and most desktop viewers show the label in the page-number box, with the physical index in brackets. If the box shows a bare number and nothing else, there are probably no labels.
• pdftk input.pdf dump_data prints PageLabelNewIndex, PageLabelStart, PageLabelPrefix and PageLabelNumStyle entries for each range. This is the fastest read.
• mutool show input.pdf trailer/Root/PageLabels shows the raw number tree for anyone who wants to see the structure directly. See mupdf introduction.

Setting page labels

This is where the tooling thins out considerably.

Adobe Acrobat: open the Page Thumbnails panel, select a range of pages, right-click → Page Labels. You get a dialog with the style, prefix, and start number — exactly matching the underlying model. This is the most direct implementation anywhere.

pdftk: update_info accepts PageLabelBegin blocks in the same format dump_data emits. Dump, edit the text, apply:

pdftk in.pdf dump_data output info.txt
# edit info.txt
pdftk in.pdf update_info info.txt output out.pdf

Clunky, scriptable, reliable.

PyMuPDF: doc.set_page_labels() takes a list of range dictionaries and writes the tree properly. This is the cleanest programmatic option.

LaTeX: the hyperref package emits page labels automatically when you use \frontmatter and \mainmatter, or \pagenumbering{roman} / \pagenumbering{arabic}. This is why a well-built LaTeX document usually has correct labels while a Word export usually does not. See how to convert PDF to LaTeX for the opposite direction.

Word, LibreOffice, InDesign exports: generally do not write page labels, even when the document has roman front matter. The printed numbers are drawn on the page; the metadata is not written. This is the single biggest reason page labels are missing in the wild.

Labels and scanning

If you are digitising books or reports, adding labels is one of the highest-value, lowest-effort steps in the process. A scan of a 400-page report with correct labels is navigable; the same scan without them requires the reader to do arithmetic on every reference.

The practical workflow: scan, OCR, then set three or four label ranges to match the printed structure. It takes two minutes per document in Acrobat, and it survives everything downstream. Related ground: how to make a PDF searchable with OCR and how to archive PDFs long term.

What breaks them

Page labels are fragile in the ways you would expect from metadata that most tools ignore:

• Merging almost always discards them, or keeps only the first document's ranges and applies them nonsensically to the whole result.
• Splitting typically drops them, leaving each piece numbered from 1.
• Round-tripping through a converter loses them, because the intermediate format has no equivalent concept.
• Page insertion shifts every subsequent physical index but does not renumber the label ranges, producing labels that are silently off by the number of pages you added.

That last one is worth watching for after any edit. If the label and the ink on the page disagree, the labels lied — check them after inserting or deleting pages, as covered in how to insert pages into PDF.

Conventions worth adopting

If you produce documents that people cite:

• Set labels whenever printed numbers differ from physical order. Front matter is the common case.
• Do not use labels as a substitute for printed numbers. They are metadata; they vanish when the document is printed. Both should exist and agree. See how to add page numbers to PDF.
• Prefer prefixes to clever styles for appendices: "A-1" is unambiguous in a way that a second sequence of plain arabic numerals is not.
• State which numbering you mean in anything that cites a page — "p. 43 (PDF p. 55)" removes the ambiguity entirely and costs six characters.

Summary

Page labels map physical sheet order onto the numbering a reader sees printed on the page. They are cheap to set, they make a scanned or paginated document genuinely navigable, and almost every common workflow — Word export, merge, split — either fails to create them or quietly destroys them. If you publish long documents, check them; if you digitise books, set them.