Imposing PDFs (pdfpages)

You write \includepdf{paper.pdf} and only one page comes in. That is the first step everyone trips over with LaTeX’s pdfpages, and the reason is that the option defaults to pages=1 — page one only. Measured: a five-page PDF pulled in with no options produced exactly one page of output. To take the lot, write pages=- (the same PDF then gave five). Learn that one character and the rest of pdfpages opens up — the package is by Andreas Matthias, and the copy in TeX Live 2024 is v0.5y, dated 2024/01/21. Prepend a cover, splice per-chapter PDFs into a thesis, lay slides out 2×2 for a handout, stamp DRAFT across every page, add entries to the bookmarks and the table of contents: this page works through each of those, compiling as it goes.

How \includepdf is used, and how it differs from \includegraphics

Load \usepackage{pdfpages} in the preamble and call \includepdf[…]{file} in the body. The difference is that it works a sheet at a time. \includegraphics puts the PDF into the text flow as a picture, so anything larger than the text block overflows and the document’s margins still apply. \includepdf starts a fresh sheet and scales the source page automatically to fit it. Measured: a PDF made at A5 (419.5 x 595.3pt) pulled into a letter-size document came out on 612 x 792pt letter sheets — the source page was scaled to the paper, not the other way round. The filename must not contain blanks.

Internally \includepdf calls \includegraphics from graphicx, so any option pdfpages does not interpret itself — trim, clip, scale, angle and the like — is forwarded straight to it. To crop the header and footer off the pages you import, write \includepdf[pages=-, trim=0 2cm 0 2cm, clip]{paper.pdf}. To stop the automatic scaling there is noautoscale, and to shift the imported page there is offset, which takes two dimensions.

\documentclass{article}
\usepackage{pdfpages}
\begin{document}

% body text ...
\includepdf[pages=-]{cover.pdf}
% ... body text continues

\end{document}

Writing the pages option: all pages, reverse order, blank leaves

The pages option lists the pages to insert and their order, comma-separated. A range is m-n; drop the m and it means the first page, drop the n and it means the last. So pages=- reads as “first to last”. The final page can also be named with the keyword last, which is only valid inside a range. Order is where this gets interesting: pages=last-1 inserts the file backwards, and measured, an eight-page PDF came out as PAGE 8 down to PAGE 1.

The other trick worth knowing is the empty {}. Put {} in the list and you get one blank leaf at that point. pages={1,{},2-21} gives you cover, blank page, then pages 1–20 of the body. Measured, pages={1,{},2} produced three pages whose extracted text was only PAGE 1 and PAGE 2 — the middle one really was blank. This is how you make every chapter of a double-sided thesis start on a right-hand page.

% cover, then one blank leaf, then body pages 1-20
\includepdf[pages={1,{},2-21}]{thesis-cover.pdf}

% every page, in reverse order
\includepdf[pages=last-1]{scan.pdf}

% a hand-picked selection, in this order
\includepdf[pages={3,1,4,1,5}]{notes.pdf}

Making a 2x2 handout with nup — and landscape writes a /Rotate

nup=across x down tiles several logical pages onto one sheet. Measured, an eight-page slide PDF imported with nup=2x2 produced two sheets, and nup=2x1, landscape produced four. Pages fill row by row by default; add column for column-major order, and columnstrict to hold that order even on the last sheet. delta puts gaps between the pages (two dimensions, as in delta=5mm 5mm) and frame boxes each one.

landscape turns the sheet, not the pages placed on it; to spin the pages themselves, use angle=90. What is interesting is that this landscape writes a /Rotate 90 into the PDF. Inspect a file built with nup=2x1, landscape using pdfinfo -f 1 -l 1 and you get Page 1 rot: 90 while the page size stays 612 x 792 — the viewer turns it for you. To suppress that, set turn=false (the default is turn=true). The pdflscape package uses the same mechanism; the page on tables wider than the text block compares them in detail.

% four slides per sheet, boxed, with a gap between them
\includepdf[pages=-, nup=2x2, frame, delta=5mm 5mm]{slides.pdf}

% two pages side by side on a landscape sheet
\includepdf[pages=-, nup=2x1, landscape]{report.pdf}

fitpaper: fit the sheet to the source PDF instead

By default the source page is scaled to your paper; fitpaper=true inverts that and changes the sheet size to match the source PDF. Measured, an eight-page A5 PDF imported into a letter-size document with fitpaper=true gave output pages of 419.527 x 595.275pt — the original A5, untouched. Use it for scans, where scaling would degrade the image, and for submission forms whose page geometry is already fixed.

There are tools for source files whose pages are not all the same size. By default the first inserted page becomes the template, and every later page is scaled to fit within its outline. To nominate a different one, use pagetemplate=⟨page number⟩; to give the size directly, templatesize={⟨width⟩}{⟨height⟩} — make it slightly larger than you want, to stay clear of rounding errors. A landscape page arriving at a portrait template is scaled down by default, but rotateoversize=true rotates it to fit instead. And when you want to print two-up and cut the stack into two copies afterwards, doublepages inserts every page twice.

Restoring page numbers and stamping DRAFT: pagecommand and picturecommand

When you want your document’s page numbers to print on the imported pages, reach for pagecommand. The option takes LaTeX code to run on each inserted page, and pdfpages.sty defines its default as \thispagestyle{empty} — which is why imported pages arrive with no folio and no running head. Change it to pagecommand={\thispagestyle{plain}} and your own page numbers appear on top of them.

There is a trap here. Overriding pagecommand for your own purposes removes the default \thispagestyle{empty} along with it. Measured, a document that passed nothing but watermark-drawing code to pagecommand printed page numbers 1, 2, 3… onto the imported pages, entirely unintended. If you do not want them, add \thispagestyle{empty} at the front of your own code.

For the stamping itself there is a dedicated hook. picturecommand takes commands executed inside a picture environment whose origin is the lower-left corner of each page — an origin that does not move even when the page is turned by landscape. Measured, an eight-page import given picturecommand={\put(30,30){\Large CONFIDENTIAL}} came back from pdftotext as PAGE 1 CONFIDENTIAL PAGE 2 CONFIDENTIAL …, stamped on every page. To stamp only the very first page, use picturecommand*.

% your own page numbers on the imported pages
\includepdf[pages=-, pagecommand={\thispagestyle{plain}}]{paper.pdf}

% stamp every imported page; the picture origin is its lower-left corner
\includepdf[pages=-,
            picturecommand={\put(30,30){\Large CONFIDENTIAL}}]{paper.pdf}

% ...and picturecommand* would stamp only the first inserted page

Assembling a thesis from per-chapter PDFs: includepdfmerge and addtotoc

The command that splices separately typeset PDFs together is \includepdfmerge. Its argument is a run of “filename, page-spec, filename, page-spec, …”, where the page-spec uses the same syntax as pages; omit it and only that file’s first page is taken. Measured, \includepdfmerge{a.pdf,1-2,b.pdf,3} produced three pages reading PAGE 1, PAGE 2, SOURCE PAGE 3. If you would rather not repeat the same options, \includepdfset{…} sets defaults for all of them, and options written on an individual \includepdf override those.

An inserted PDF does not, by itself, show up in the table of contents or the bookmarks. addtotoc fixes that; it takes five comma-separated arguments: addtotoc={⟨page number⟩,⟨section⟩,⟨level⟩,⟨heading⟩,⟨label⟩}. The page number counts within the pages you inserted, the section is a sectioning name such as section, the level is its depth as a number, the heading is the string to print in the contents, and the label is a name you can point \ref and \pageref at. The five must stay in that order.

Paired with hyperref, that one option does three jobs at once. Measured: with hyperref loaded, addtotoc={1,section,1,Imported paper,sec:paper} wrote \contentsline {section}{\numberline {2}\ignorespaces Imported paper}{2} into the .toc, produced \BOOKMARK [1][-]{section.2}{Imported paper}{} in the .out, and made \ref{sec:paper} and \pageref{sec:paper} resolve correctly from the body. A contents entry, a PDF bookmark and a working cross-reference, all from one line. For the list of figures or tables there is addtolist.

\documentclass{article}
\usepackage{hyperref}
\usepackage{pdfpages}   % load pdfpages after hyperref
\begin{document}
\tableofcontents
\section{Front matter}

% one contents entry, one PDF bookmark, one \ref target
\includepdf[pages=-,
            pagecommand={\thispagestyle{plain}},
            addtotoc={1,section,1,Imported paper,sec:paper}]{paper.pdf}

\section{After}
See \ref{sec:paper} on page \pageref{sec:paper}.

% assemble a thesis from separately typeset parts
\includepdfmerge{frontmatter.pdf, -, chap1.pdf, -, chap2.pdf, -}
\end{document}

The order signature=8 produces: 8, 1, 2, 7, 6, 3, 4, 5

To make a saddle-stitched booklet, the pages have to be reordered so that they come out right once folded. Give pdfpages’ signature option a multiple of four and it arranges the pages into signatures of that size, imposing them automatically with nup=1x2 or nup=2x1, whichever the orientation calls for. Measured: an eight-page PDF with signature=8, landscape produced four sides, and the extracted page order was PAGE 8, PAGE 1, PAGE 2, PAGE 7, PAGE 6, PAGE 3, PAGE 4, PAGE 5. Print that double-sided on two sheets, stack them and fold once, and the pages open in the order 1 to 8.

Note that pages=-, nup=1x2, landscape does no reordering at all. It merely puts two pages side by side; fold that and the sequence is wrong. If you want signatures, you must use signature. For more elaborate imposition — several signatures, creep, crop marks — the dedicated booklet package is also in TeX Live.

% a saddle-stitched booklet in signatures of eight pages
\includepdf[pages=-, signature=8, landscape]{booklet-doc.pdf}

Importing loses the links: pax and the link option

\includepdf copies only the appearance of each page. Links inside the source PDF stop working — and the pdfpages manual is explicit that it is not only links but every kind of PDF annotation that is lost. To keep the original links, pair it with pax (Heiko Oberdiek), which extracts the annotations and puts them back.

In the other direction, pdfpages can create link targets of its own. Pass link=true and each inserted page becomes a target named ⟨filename⟩.⟨page number⟩, so \hyperlink{paper.pdf.3}{…} in your text jumps to imported page 3. linkname=mylink changes the base name, and linkfilename, linktodoc, linkfit and newwindow handle links to external files. The article-thread options thread and threadname belong to the same family.

Engines and drivers: when pLaTeX and dvipdfmx give you blank pages

The engines the pdfpages manual lists are pdfTeX, VTeX, XeTeX, LuaTeX and pTeX, so it works under pdfLaTeX, LuaLaTeX, XeLaTeX and (up)pLaTeX alike. It does assume an engine that writes PDF directly, though: on a DVI route the PDF cannot be imported and blank pages go in instead. In the pLaTeX plus dvipdfmx setup common in Japanese work, importing the PDF is dvipdfmx’s job, so the graphics driver has to be named correctly. The manual’s recommended spelling is to pass dvipdfmx as a class option.

% the driver the pdfpages manual recommends for the platex route
\documentclass[dvipdfmx]{article}
\usepackage{pdfpages}

% ...or state it explicitly on graphicx
% \usepackage[dvipdfmx]{graphicx}

That route has one more quirk worth knowing. pdfpages calls the external program extractbb to find out how many pages the imported PDF has, but if a matching .xbb file already exists it uses that instead of calling extractbb. Replace the source PDF and leave a stale .xbb behind and the page count no longer matches, so the insertion goes wrong; regenerate the .xbb whenever the PDF changes. One last trap, for documents with a page background: the first \pagecolor must come before \usepackage{pdfpages}.