Gkhtmltopdf

Gkhtmltopdf is mean Gecko HTML to PDF converter.

Developed as an alternative to wkhtmltopdf. This gem converts HTML to PDF using Firefox's Geckodriver.

1. Firefox

   • Ubuntu

     $ apt install -y firefox
     $ apt install -y fonts-noto # recommended

   • Debian

     $ apt install -y firefox-esr
     $ apt install -y fonts-noto # recommended

2. geckodriver

• Linux (Ubuntu / Debian)

  $ wget "https://github.com/mozilla/geckodriver/releases/download/v0.36.0/geckodriver-v0.36.0-linux64.tar.gz" -O /tmp/geckodriver.tar.gz
  $ tar -xzf /tmp/geckodriver.tar.gz -C /usr/local/bin

3. gem install

• bundler

  $ bundle add gkhtmltopdf

• other

  $ gem install gkhtmltopdf

⚠️ Security Warning for Web Frameworks (e.g., Ruby on Rails): If you are accepting URLs from untrusted users, you must implement strict SSRF protection. Do not pass user-input URLs directly without network-level isolation. Please read the SSRF section below for details.

require 'gkhtmltopdf'
# over network
Gkhtmltopdf.convert('https://example.com', 'example_com.pdf')
# local file
Gkhtmltopdf.convert('file:///foo/bar/test.html', 'local.pdf')
# with option (print background)
Gkhtmltopdf.convert('https://f6a.net/oss/', 'with_bg.pdf', print_options: {background: true})

Additionally, in version 1.0.0 we added the following syntax.
If you want to generate multiple PDFs faster, use this:

require 'gkhtmltopdf'
Gkhtmltopdf.open do |gkh2p|
  gkh2p.save_pdf('https://example.com', 'example_com.pdf')
  gkh2p.save_pdf('file:///foo/bar/test.html', 'local.pdf')
  gkh2p.save_pdf('https://f6a.net/oss/', 'with_bg.pdf', print_options: {background: true})
end

# over network
$ gkhtmltopdf https://example.com/ example_com.pdf
# local file
$ gkhtmltopdf /foo/bar/test.html local.pdf
# with option (print background)
$ gkhtmltopdf https://f6a.net/oss/ with_bg.pdf --background
# other option
$ gkhtmltopdf --help

Due to the W3C WebDriver specification, Geckodriver does not throw an error if the target URL returns an HTTP error status (such as 404 Not Found or 500 Internal Server Error). If the browser successfully renders an error page, that error page will simply be converted into a PDF. If you need to verify the status of a URL or branch your logic based on HTTP status codes, please perform a pre-flight check using an HTTP client (e.g., Net::HTTP or Faraday) before passing the URL to this gem.

SSRF is Server-Side Request Forgery.

This gem passes the provided URL directly to Headless Firefox.
If you integrate this gem into a web service that accepts arbitrary URLs from untrusted users, it may be vulnerable to SSRF and DNS Rebinding attacks.
Attackers could potentially generate PDFs of internal network resources (e.g., localhost, 192.168.0.1, 169.254.169.254 for cloud metadata).

Recommendation: Do not rely solely on application-level URL validation. If you process untrusted URLs, strongly consider using network-level isolation (such as Docker container networking restrictions, iptables, or an egress proxy) to block access to private/internal IP ranges.

The following errors inherit Gkhtmltopdf::Error, so you can handle them as follows:

begin
  Gkhtmltopdf.convert('ftp://example.com', 'example_com.pdf')
rescue Gkhtmltopdf::Error => e
  puts e.class   # -> Gkhtmltopdf::URLSchemeInvalid
  puts e.message # -> Invalid URL scheme: (ftp)
end

Firefox or Geckodriver path unresolved. Follow the installation steps in 1. Install to set up.

Raised when the URL scheme is invalid (e.g., ftp://, about://) or the hostname is missing (e.g., f6a.net).

Response from Firefox/Geckodriver is not as expected.

This gem acts as a wrapper and communicates with the following external open-source tools.

We are deeply grateful to their developers:

• Firefox: Licensed under the MPL-2.0.
• Geckodriver: Licensed under the MPL-2.0.

Note: Gkhtmltopdf does not bundle these binaries. When you install and use Firefox and Geckodriver in your environment, please refer to their respective licenses.

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