Manipulation · Ruby
Merge PDF files in Ruby
Combine, split, reorder and rotate PDF pages from Ruby. rust-pdf parses each document into an editable model, renumbers and remaps every object correctly on merge, and rebuilds a clean page tree on output.
Last updated: 2026-06-29
Why Ruby needs this
Prawn writes new PDFs but cannot open existing ones, so combining or splitting documents in Ruby usually means a CombinePDF detour or shelling out to a pdftk binary. rust-pdf parses real files and edits them in place.
Merging and splitting are list operations on a flat page order: append another document, pull out a subset, reverse, rotate or delete pages, then save. Because the parser reads classic and cross-reference streams, object streams and RC4 or AES encrypted input, it handles files it never wrote.
Load each PDF with EditableDoc.load_file in a Rails controller or a Sidekiq worker, chain merge, reorder_pages and rotate_page, then rescue RustPdf::Error on a malformed upload; it is pure FFI through Fiddle, so there is no pdftk binary to install.
- Merge whole documents, extract page subsets, reorder with a permutation, rotate or delete pages.
- Objects are renumbered and references deep-remapped, so merged files stay valid.
- Reads classic and xref streams, object streams and RC4 / AES encrypted input.
Merge PDFs in Ruby with rust-pdf
Install with RubyGems, then call the same idiomatic API every rust-pdf binding shares. The snippet below is real Ruby code from the reference docs.
gem install rustpdf
a = RustPdf::EditableDoc.load_file("a.pdf")
b = RustPdf::EditableDoc.load_file("b.pdf")
a.merge(b) # a now has a's pages followed by b's
a.rotate_page(0, 90)
a.reorder_pages((0...a.page_count).to_a.reverse)
a.save("merged.pdf")
b.close
subset = a.extract_pages([0, 2]) # pages 1 and 3
subset.save("subset.pdf")
subset.close
a.closeThis is part of the free tier in Ruby. No license required.
Full Ruby reference in the documentation.
Merging in Ruby: FAQ
Can I merge more than two PDFs in Ruby?
Yes. Load each document and call merge for each one; pages are appended in order. You can then reorder, rotate or extract any subset before saving.
Does merging keep the files valid?
Yes. On merge every object from the other document is renumbered and its references are deep-remapped, and the real page tree is rebuilt on output, so the result passes qpdf and mutool.
Is merging free?
Yes. Loading, merging, splitting, reordering and text extraction are all part of the free tier in Ruby. You only need a license for the corporate features such as PDF/A, signatures and encryption.
Can I merge user-uploaded PDFs in a Rails app?
Yes. Load each upload with EditableDoc.load_file in a controller or a Sidekiq worker, merge or extract pages, then save. The parser reads classic, cross-reference and object streams plus encrypted input, and a bad upload surfaces as a RustPdf::Error you can rescue.
Reshape PDF documents straight from Ruby
One Rust core, the same output across every language. Prototype for free, license the corporate features when you ship.