Combining PDFs in a Ruby on Rails application
Rails PDFs

Published on 27/10/2021 by Jerry Weyer

When creating PDFs you might need to combine different PDFs into one larger file, for example if you want to add a cover page to a PDF report you are generating, or if you want to add your general terms to an invoice PDF you are sending via your application.

CombinePDF is a pure Ruby solution to parse PDF files and combine (merge) them with other PDF files, watermark them or stamp them.

Combining PDFs, for example an invoice and terms and conditions, is pretty straight-forward:

  pdf =
  pdf << CombinePDF.load("invoice.pdf")
  pdf << CombinePDF.load(Rails.root.join('lib', 'data', 'terms.pdf').to_s) "combined.pdf"

CombinePDF offers the handy parse method to handle PDFs from a remote location. This can be especially useful when working with ActiveStorage files hosted on Amazon S3 and similar services.

In one of our apps, our users can upload documents that will be combined into a larger PDF. It is not always possible to scan for compatible PDFs during the upload, and we don't want to abort the entire process when an incompatible PDF is uploaded.

CombinePDF offers the allow_optional_content option, which allows you to merge PDFs with optional content sections without raising an exception. We encountered a few instances where uploaded PDFs were not correctly displayed when using this option, but it allows the user to get the final PDFs and assess themselves if they want to replace the PDF in question by a compatible version.

In this series on "Managing PDFs in a Ruby on Rails application", I'm listing some tools I found to be useful in order to create, import, export, fill out, convert and generally manage PDFs in a Ruby on Rails application:

Please head to the article if you want to comment or discuss this post.