Why Merging PDFs Deletes Your Bookmarks (and What Else Disappears)

Take two PDF manuals, each with a proper clickable table of contents down the side. Merge them. Open the result and the sidebar is empty.

Nothing failed. There's no warning, and every page is present and correct. The bookmarks just aren't, and they were never going to be, because of one argument in the line of code that does the joining.

I went looking after noticing our own merge does it too. Bookmarks turn out to be the most visible casualty rather than the only one. The document title goes as well, fillable forms stop being fillable, and internal cross-page links survive as clickable rectangles pointing at nothing. Meanwhile a password-protected file in your batch doesn't stop the merge at all. It just isn't in the result.

There's one rule underneath all of it. Everything below is measured on real files, and the numbers are the ones I got back.

The rule that predicts what a merge keeps

A PDF isn't a stack of pages. It's a small object database with a catalog at the top, and the things you care about live at one of two levels.

Page level: the page's content, the fonts and images it uses, its dimensions, its rotation, and its annotations, which covers link rectangles, form widgets and comments.

Document level: the outline tree that draws your bookmarks, the form dictionary that registers fields as a form, named destinations, and the info dictionary holding title, author and keywords.

Merging copies pages. It walks each file, lifts the page objects out, and stacks them into a brand-new document. Anything hanging off a page comes along. Anything registered up in the catalog stays behind, because the new document builds a fresh catalog of its own.

That's it. Page level survives, document level is at risk. Every specific behaviour below is that rule playing out.

Why merging PDFs deletes your bookmarks

Bookmarks aren't attached to pages. They're a separate tree in the catalog, and each entry holds a title plus a destination that points at a page. Copy the pages and the tree is left where it was.

A merge library can rebuild that tree as it goes. PyPDF2, which our merge runs on, is perfectly capable of it: the append method takes an import_outline argument that defaults to True. Our script passes False.

merger.append(pdf_file, import_outline=False)

One word, and the sidebar comes out blank.

I built two files to watch it happen. Three bookmarks in the first, one in the second, six pages between them:

--- INPUT: a_report.pdf ---
  pages: 3
  outline entries: 3 -> ['Introduction', 'Findings', 'Appendix']

--- INPUT: b_addendum.pdf ---
  pages: 2
  outline entries: 1 -> ['Addendum start']

--- OUTPUT: out_clean.pdf ---
  pages: 6
  outline entries: 0 -> []

Six pages arrived. Four bookmarks did not.

Is switching it off the wrong call? I don't think so. Importing outlines from several files hands you a flat pile of top-level entries with no parent structure, and when two files share section names you get duplicates you can't tell apart. An empty sidebar beats forty ambiguous entries. But it is a decision, and nothing on screen tells you it was taken.

The document title goes with them

Same mechanism, far less noticed. Title, author, subject and keywords sit in the info dictionary, which is document level.

My first test file was titled Quarterly Report, by Test Author, with keywords set. Here is the merged file's metadata in full:

metadata: {'/Producer': 'PyPDF2'}

Every field gone, replaced by the name of the library that wrote the file. A second input from a completely different generator gave the same result, so it isn't a quirk of one file.

This matters more than it sounds. Browsers label the tab with a PDF's title rather than its filename, so a document you'd titled carefully opens as untitled once merged. If the title does real work for you, set it again afterwards.

Fillable forms come out as decoration

This is the one that surprised me.

Merge a PDF containing form fields and the boxes are still visibly on the page. Click one. Nothing happens.

The widgets are page-level annotations, so they survive. The form dictionary that registers them as an actual form is document level, so it doesn't. You end up with a drawing of a form rather than a form. Measured on a one-page file holding a text field and a checkbox:

before:  has /AcroForm: True   form fields: ['agreed', 'applicant_name']
after:   has /AcroForm: False  pages carrying /Annots: 1

The annotations came through. The registry didn't.

The same thing finishes off a digital signature, since signature fields are entries in that dictionary too. It was doomed regardless: a signature covers a byte range of the original file, and a merge rewrites every byte.

If you need a completed form in a merged bundle, fill it and flatten it first. Flattening converts the field values into ordinary page content, which is page level, which survives.

External links survive, internal links break quietly

Link annotations are page level, so all of them come through. Whether they still work depends entirely on where they point.

An external link is self-contained, with the address sitting right there in the annotation. I put a Wikipedia link on page one, merged it behind two other pages, and it arrived untouched.

An internal link is a reference to another page object in the same document, and that's where it comes apart. My test file had a link on page one jumping to its own page three. After merging behind two front-matter pages the appendix is page five, so that's where the link should go.

It doesn't go anywhere. The page objects in the merged file's page tree are numbered 4, 8, 10, 18 and 20. The link's destination points at object 13, which is a page object that got copied into the file but never wired into the page tree:

page object idnums in page tree: [4, 8, 10, 18, 20]
link Dest target idnum: 13
target object /Type: /Page
target is in page tree: False

So the rectangle is still clickable and there's nothing valid on the other end. A dead link that looks exactly like a working one. If your document carries a hand-built set of internal jumps, a merged PDF is the one case where clicking through all of them is worth the time.

The files that never make it in at all

Everything so far has been about content inside a file. This is about a whole file going missing.

Our merge script is deliberately forgiving. It checks each PDF, and when the check complains it warns and tries anyway. If adding the file then fails, that file is skipped and the merge carries on. The reasoning is sound enough: one malformed file out of eight shouldn't cost you the other seven.

The price is that failure looks identical to success. Three files in, the middle one truncated:

Adding file 1/3: a_report.pdf
Adding file 2/3: e_damaged.pdf
Warning: Could not add file e_damaged.pdf: EOF marker not found
Skipping this file and continuing with merge...
Adding file 3/3: b_addendum.pdf
Success: Merged 3 PDFs into out_damaged.pdf

OUTPUT pages: 5

Success, three PDFs, exit code zero. Five pages, out of files that held six between them.

Password-protected files land in exactly the same hole, and this is the part worth knowing. A PDF that needs a password to open reports back File has not been decrypted when the merger tries to read it, which the script treats as one more awkward file and skips accordingly. I tested both RC4 and AES encryption and got the same outcome from each. The merge reports success and the locked file simply isn't in it.

So if one of your files needs a password, remove the password first and merge the unlocked copy. Don't wait to be told.

Two different things get called a password here. A file with an open password, where you can't read it without typing something, gets dropped. A file with only a permissions password, which opens fine but restricts printing or copying, merges normally, since the pages are readable either way. In my test it contributed all three of its pages.

And the far end of the same behaviour: if every file in the batch fails, you still get a download. A 312-byte PDF containing zero pages.

What survives a merge, unchanged

Two things people brace for and don't need to. Quality holds, because no page is rebuilt on the way through, so text stays selectable and a scan is as sharp as it arrived. Page sizes hold individually too: I merged a US Letter file with an A4 one and both came out intact in the same document rather than one being stretched to match.

File size won't be the sum of the parts either. My three test files were 11,094 bytes together and came out as 8,844, because every input carries its own cross-reference table and trailer and the output needs only one set.

The ten-second check after every merge

Add up the page counts of your originals before you start, then compare against the merged file. That one number catches every silent drop described above, and it's right there in the toolbar's page counter.

Short by a few pages means a file didn't make it, and the two likely culprits are an open password or a damaged file. For a damaged file, repairing it first works better than merging harder.

The other habit worth having: set the order in the interface rather than by renaming files. Where you can drag the files into position, do that, because the list order is what gets submitted. Drag your PDFs into the order you want and the card at the top becomes page one.

Getting bookmarks back after a merge

You can't recover them from the merged file. The tree was never copied, so there's nothing inside to restore. Rebuilding is the only route, and in the order I'd try it:

1. Don't merge. Keep the files separate and send a folder or a zip. Often the bookmarks mattered more than having one file did.
2. Merge, then add the outline once in a desktop editor. One entry per section is tedious at forty and completely fine at six.
3. Skip bookmarks, add a contents page at the front with the merged page numbers on it. Less elegant, and it survives absolutely everything you do to the file afterwards.

One thing worth pushing back on: merging isn't a layout operation. It won't reflow text, renumber pages, or resize anything. If you want a document that reads as one document, with a single page sequence and consistent margins, a merge gives you a container rather than that. The page numbers in the result are whatever each source file had printed on it, which is three sequences all starting at one.

So the question before merging is narrow: does anything I care about live in the sidebar, the form fields or the document properties? If yes, deal with it first, because afterwards there's nothing to recover. If no, and for most merges it really is no, stack the files, check the page count, and get on with your day.