Generate PDF from HTML using PhantomJS!

Supporting URL, FILE and STRING formats for HTML resource.

Why PhantomPDF?

Within the Ruby community, there is no simply way to generate PDF from HTML. You must setup dependences separate and then call some wrapped methods around. When you manage several servers or need to do migrations around, things become much more terrible!

PhantomPDF was born to simplify those. It brings simple API and easy maintenance.

Yes, PhantomPDF is simply! You only need to take care of your HTML layout. And then put remaining work to PhantomPDF.

How to start?


For Gemfile project

Adding following to your Gemfile

gem 'phantompdf'

and then execute

$ bundle
For normal project
$ gem install phantompdf

That's all! Pretty simple?!


Quick starts
require 'phantompdf'

options = {
  :format => 'A4',
  :margin => '1cm'
output_file = '/tmp/phantompdf_google.pdf'

# for *URL* resource
url = ''
url_generator =, output_file, options)
returned_file = url_generator.generate  # If output_file is valid(writable) returned_file == output_file, otherwise returned_file should be temp file of your OS.

# for *FILE* resource
file = 'file://path/to/file.html'
file_generator =, output_file, options)
returned_file = file_generator.generate

# for *STRING* resource
html = '<h1>Hello, PhantomPDF!</h1>'
html_generator =, output_file, options)
returned_file = html_generator.generate

# want to dynamic output?
url_generator.generate('/tmp/dynamic_phantompdf_google.pdf')  # This will output pdf file to /tmp/dynamic_phantompdf_google.pdf though you pass *output* arg when creating generator instance.

You can configure PhantomPDF globally in your project, such as Rails' initializers principle.

PhantomPDF.configure do |config|
  # default pdf output format, e.g. "5in*7.5in", "10cm*20cm", "A4", "Letter"
  :format            => 'A4',

  # default pdf header, formatted in [headerHeight*]headerString(HTML is supported)
  # default to 1.2cm when you omit headerHeight
  # you can use *%{pageNum}* and *%{pageTotal}* to refer current values of page
  # example: 1.2cm*<h5>PhantomPDF header %{pageNum}/%{pageTotal}
  :header            => nil,

  # default pdf footer, formatted in footerHeight*footerString(HTML is supported)
  # you can use *%{pageNum}* and *%{pageTotal}* to refer current values of page
  # example: 0.6cm*<h5>PhantomPDF header %{pageNum}/%{pageTotal}
  :footer            => nil,

  # default page margin
  :margin            => '1cm',

  # default page orientation, 'portrait' or 'landscape'
  :orientation       => 'portrait',

  # default page zoom factor
  :zoom              => 1,

  # default cookies, only used for *URL* resource
  :cookies           => {},

  # PhantomJS running timeout
  :timeout           => 90000,

  # pdf rendering timeout, increase if your HTML page is big
  :rendering_timeout => 1000

You can also configure PhantomPDF in place when needs.

# for *URL* resource
url = ''
url_generator =, output_file, options)
url_generator.options.header = '0.8cm*<h3>Configure PhantomPDF dynamic</h3>'
returned_file = url_generator.generate
# create PhantomPDF, output=nil, options={})

# generate pdf

# raise PhantomPDF::RenderingError when failed to generate pdf

# get generated pdf as string


If you'd like to help improve PhantomPDF or you find some bugs. You can contribute to it by following:

  • Submit an issue describing your problem
  • Fork your repo and work your magic
  • Test your code as far as possible
  • Submit a pull request when you finished hack


PhantomPDF is released under MIT license.


Spring MC