Comparison

A Rails alternative to Wicked PDF

Wicked PDF is one of the most-used Rails gems for PDF generation. Under the hood it is a thin wrapper around wkhtmltopdf, a binary that was officially abandoned in 2023. The rendering engine is a forked WebKit from roughly 2015: CSS Grid does not work, Flexbox support is partial and buggy, and custom properties are unsupported. Worse, wkhtmltopdf ships platform-specific binaries that routinely break on ARM (Apple Silicon, Render, Railway's default build images) and require a string of X11 system libraries on every server. PDFPipe renders with a modern engine from a plain HTTP call, with no binary to install and no platform-specific gotchas.

Wicked PDF versus a dedicated PDF API

The wkhtmltopdf binary problem

wkhtmltopdf is not a Ruby gem. It is a compiled C++ binary that must be installed on every machine where your Rails app runs. On a local macOS ARM machine you need a different build than on a Linux x86-64 CI container. The wkhtmltopdf-binary gem bundles platform-specific binaries and works most of the time on x86-64 Linux, but fails silently or crashes on ARM. Moving to Render, Railway, or any ARM-based build environment means tracking down a compatible binary, adding it to your Dockerfile, and adding its X11 dependencies. A Dockerfile for a Rails app using Wicked PDF typically grows by 10-15 lines of system package installs just to support one gem.

Modern CSS support

The wkhtmltopdf rendering engine is based on a WebKit snapshot from roughly 2015. CSS Grid is completely unsupported. Flexbox works for simple cases but breaks on nested layouts, alignment edge cases, and gap properties. CSS custom properties do not work. If your Rails app uses Tailwind CSS (which relies heavily on Flexbox and Grid), your PDF templates need a completely separate stylesheet maintained in parallel. PDFPipe uses a modern rendering engine, so the same Tailwind or plain CSS that works in the browser works in the PDF.

Before and after

# Gemfile
gem "wicked_pdf"
gem "wkhtmltopdf-binary"  # platform-specific binary — fails on ARM

# Dockerfile (you still need this for production)
RUN apt-get update && apt-get install -y \
    wkhtmltopdf \
    libxrender1 xfonts-75dpi xfonts-base \
    # ... 6-10 more X11 dependencies

# Controller
class InvoicesController < ApplicationController
  def show
    @invoice = Invoice.find(params[:id])
    respond_to do |format|
      format.pdf do
        render pdf: "invoice-#{@invoice.id}",
               template: "invoices/show",
               layout: "pdf"
      end
    end
  end
end

Replace with a plain HTTP call. No gem, no binary, no Dockerfile changes:

# No gem required. Use Net::HTTP or Faraday — whatever your app already has.
require "net/http"
require "uri"
require "json"

class InvoicesController < ApplicationController
  def show
    @invoice = Invoice.find(params[:id])
    html = render_to_string(template: "invoices/show", layout: "pdf")

    uri = URI("https://api.pdfpipe.xyz/v1/pdf")
    req = Net::HTTP::Post.new(uri, {
      "Authorization" => "Bearer #{ENV.fetch("PDFPIPE_API_KEY")}",
      "Content-Type"  => "application/json",
    })
    req.body = { html: html, options: { format: "A4" } }.to_json

    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    raise "PDF render failed: #{res.code}" unless res.is_a?(Net::HTTPSuccess)

    send_data res.body,
              filename:    "invoice-#{@invoice.id}.pdf",
              type:        "application/pdf",
              disposition: "inline"
  end
end

When Wicked PDF still makes sense

Wicked PDF is a reasonable choice when your Rails app runs on a fixed x86-64 Linux server that you control, your PDF templates use only basic CSS that wkhtmltopdf supports, and you cannot make outbound HTTP calls to external services due to network policy. It is also free to run, which matters for very low-volume or internal tools where the binary deployment burden is a one-time cost. For any project using modern CSS, deploying to ARM or container platforms, or hitting rendering issues with current templates, removing the binary dependency eliminates an entire category of infrastructure problems.