Getting Started


HexaPDF is a PDF library written in the Ruby programming language. To use it you first need to install a Ruby interpreter for your operating system (Linux, Windows, macOS and many others are supported). Please consult the official documentation for the required steps - don’t worry, it is very easy! Just ensure that you have Ruby version 2.6 or above (better is 3.0 or above) installed as prior versions are not supported.

If you are new to Ruby, you might wanna have a look at a Ruby tutorial first, to get acquainted with the language. HexaPDF is 100% Ruby and provides a very idiomatic interface. So once you know Ruby, you should feel right at home with HexaPDF!

At the Ruby website you will find all the necessary materials, whether you are new to programming entirely or you already know a few other languages.

Once the Ruby interpreter is available, installing HexaPDF as a Rubygems package is as easy as executing

gem install hexapdf

from the command line. This will install HexaPDF and its few dependencies.

To make sure that HexaPDF is correctly installed, you can run the following command which returns the installed version:

hexapdf version


The HexaPDF package contains the library as well as the hexapdf CLI application. The application can be used to perform common tasks like merging PDF files, decrypting or encrypting PDF files and so on. See the CLI manual page for details.

When HexaPDF is used as a library, it can be used to do all the tasks that the command line application does and much more. Here is a simple “Hello World” example that shows how to create a PDF file:

require 'hexapdf'

doc =
page = doc.pages.add
canvas = page.canvas
canvas.font('Helvetica', size: 50).
  fill_color(0, 128, 255)
canvas.text("Hello World", at: [150, 396])

To get more information on what is going on in this code example, have a look at the Creating a PDF from Scratch tutorial page.

Feature Overview

Documentation Organization

The main documentation is organized by topic and those topics are visible in the sidebar. So let’s say you are a newcomer, then you would usually start at Basics. You need to work with interactive forms? Head over to Interactive forms.

Each topic section contains basic information about the topic itself. Furthermore, it may also contain additional in-depth and background information, tutorials, how-tos and examples, all pertaining to the topic at hand.

The reason for organizing the documentation by topic is that working with PDFs can entail many different things. Some need to create new PDF documents while others need to fill out forms or add digital signatures. Through organizing by topic users can get quickly up to speed with what they need.

Additional documentation that doesn’t belong to a topic, like the API reference or the changelog can be found at the bottom of the side menu.

If you don’t find what you are looking for in the available topic sections, use the search field at the top of the website to search for keywords. You will usually get some results pointing to parts of the API reference which might be of help.

If you need still need help, open an issue or contact me.