Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
F

ferrum_pdf

> 编程语言
Open source

A PDF generator for Rails using Ferrum & headless Chrome

525 stars0 likes1 views
WebsiteGitHub

About

A PDF generator for Rails using Ferrum & headless Chrome

FerrumPdf

PDFs & screenshots for Rails using Ferrum & headless Chrome.

Inspired by Grover, but without the Node.js and puppeteer dependencies.

Installation

First, make sure Chrome is installed. Then run the following or add the gem to your Gemfile:

ruby
bundle add "ferrum_pdf"

Usage

You can use FerrumPdf to render PDFs and Screenshots

PDFs

There are two ways to render PDFs:

  • render ferrum_pdf: {} in Rails
  • FerrumPdf.render_pdf

Render PDFs from Rails controllers

Use the ferrum_pdf renderer in Rails controllers to render a PDF from the current action.

ruby
def show
  respond_to do |format|
    format.html
    format.pdf { render ferrum_pdf: {}, disposition: :inline, filename: "example.pdf" }
  end
end

You can also customize which template is rendered. This will render the template to string with render_to_string in Rails, then pass it along to Chrome. For example, you can add headers and footers using pdf_options and use a specific layout:

ruby
def show
  render ferrum_pdf: {
    display_header_footer: true,
    header_template: FerrumPdf::DEFAULT_HEADER_TEMPLATE,
    footer_template: FerrumPdf::DEFAULT_FOOTER_TEMPLATE
  },
  layout: "pdf",
  template: "pdf",
  disposition: :inline,
  filename: "example.pdf"
end

Render PDFs

FerrumPdf can generate a PDF from HTML or a URL:

ruby
FerrumPdf.render_pdf(html: content)
FerrumPdf.render_pdf(url: "https://google.com")

The full list of options:

…

See Chrome DevTools Protocol docs and Ferrum's pdf docs for the full set of options.

Screenshots

There are two ways to render Screenshots:

  • render ferrum_screenshot: {} in Rails
  • FerrumPdf.render_screenshot

Render Screenshots from Rails controllers

Use the ferrum_screenshot renderer in Rails controllers to render a PDF from the current action.

ruby
def show
  respond_to do |format|
    format.html
    format.png { render ferrum_screenshot: {}, disposition: :inline, filename: "example.png" }
  end
end

You can also customize which template is rendered. This will render the template to string with render_to_string in Rails, then pass it along to Chrome.

ruby
def show
  render ferrum_screenshot: {
    format: "png" # or "jpeg"
    quality: nil # Integer 0-100 works for jpeg only
    full: true # Boolean whether you need full page screenshot or a viewport
    selector: nil # String css selector for given element, optional
    area: nil # Hash area for screenshot, optional. {x: 0, y: 0, width: 100, height: 100}
    scale: nil # Float zoom in/out
    background_color: nil # Ferrum::RGBA.new(0, 0, 0, 0.0)
  },
  layout: "example",
  template: "example",
  disposition: :inline,
  filename: "example.png"
end

See Ferrum's screenshot docs for the full set of options.

Render Screenshots

FerrumPdf can generate a screenshot from HTML or a URL:

ruby
FerrumPdf.render_screenshot(html: content)
FerrumPdf.render_screenshot(url: "https://google.com")

The full list of options

…

Configuration

You can set default values for page loads, PDF renders, and screenshot renders with the configure block.

…

Configuring the Browser

You can set the default browser options with the configure block.

See Ferrum's Customization docs for a full list of options.

ruby
FerrumPdf.configure do |config|
  config.window_size = [1920, 1080]

  # config.process_timeout = 30 # defaults to 10
  # config.browser_path = '/usr/bin/chromium'

  # For use with Docker, but ensure you trust any sites visited
  # config.browser_options = {
  #   "no-sandbox" => true
  # }
end

For Docker, seccomp is recommend over --no-sandbox for security: https://github.com/jlandure/alpine-chrome?tab=readme-ov-file#3-ways-to-securely-use-chrome-headless-with-this-image

To add Chrome to your Docker image:

dockerfile
RUN apt-get update && apt-get install gnupg wget -y && \
    wget --quiet --output-document=- https://dl-ssl.google.com/linux/linux_signing_key.pub | gpg --dearmor > /etc/apt/trusted.gpg.d/google-archive.gpg && \
    sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' && \
    apt-get update && \
    apt-get install google-chrome-stable -y && \
    rm -rf /var/lib/apt/lists/*

Browser Management

FerrumPdf uses a single browser instance per Ruby process that is automatically created when needed using your configuration settings:

ruby
# Browser is auto-created on first use
FerrumPdf.render_pdf(url: "https://example.org")

You can also set a custom browser instance:

ruby
# Set a custom browser with specific options
custom_browser = Ferrum::Browser.new(window_size: [800, 600], headless: false)
FerrumPdf.browser = custom_browser

# All subsequent calls will use this browser
FerrumPdf.render_pdf(url: "https://example.org")

To safely shut down the browser process:

ruby
# This will quit the current browser and set it to nil
FerrumPdf.browser = nil

# Next call will auto-create a new browser
FerrumPdf.render_pdf(url: "https://example.org")

[!TIP] Thread Safety: FerrumPdf is thread-safe within a single Ruby process. Multiple threads can safely use FerrumPdf concurrently, and they will share the same Chrome browser instance. However, each Ruby worker process will have its own separate Chrome instance.

If you need multiple browsers, you can pass the browser option when rendering:

ruby
other_browser = Ferrum::Browser.new
FerrumPdf.render_pdf(url: "https://example.org", browser: other_browser)

Debugging

One option for debugging is to use Chrome in regular, non-headless mode:

ruby
FerrumPdf.configure do |config|
  config.headless = false
end

FerrumPdf also allows you to pass a block for debugging. This block is executed after loading the page but before rendering the PDF or screenshot.

ruby
FerrumPdf.render_pdf(url: "https://gooogle.com") do |browser, page|
  # Open Chrome DevTools to remotely inspect the browser
  browser.debug

  # Or pause and poke around
  binding.irb
end

The block will receive the Ferrum::Browser and Ferrum::Page objects which you can use for debugging.

Contributing

If you have an issue you'd like to submit, please do so using the issue tracker in GitHub. In order for us to help you in the best way possible, please be as detailed as you can.

To run the test suite, run:

bash
bin/test

License

The gem is available as open source under the terms of the MIT License.

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Ruby

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言