Install Asciidoctor PDF

On this page, you’ll learn how to install Asciidoctor PDF. The page documents the prerequisites you’ll need, the command you’ll use to install Asciidoctor PDF, and a catalog of optional dependencies you can install to unlock additional features. You can also find some troubleshooting advice if the installation goes wrong.

Prerequisites

Asciidoctor PDF is a Ruby application. Therefore, to use it, you’ll need a Ruby runtime.

The supported Ruby runtimes are Ruby 2.7 or greater and JRuby 9.2 or greater. However, we always recommend using the most recent release of Ruby or JRuby. All required libraries (i.e., gems) will be installed automatically when you install Asciidoctor PDF, which will be covered in the next section.

To check if you have Ruby available, run the ruby command to print the installed version:

$ ruby -v

Make sure this command reports a Ruby version that starts with 2.7 (or a JRuby version that starts with 9.2). If so, you’re ready to proceed. If not, head over to rvm.io to get RVM and use it to install Ruby.

System encoding

Asciidoctor assumes you’re using UTF-8 encoding. To minimize encoding problems, make sure the default encoding of your system is set to UTF-8.

If you’re using a non-English Windows environment, the default encoding of your system may not be UTF-8. As a result, you may get an Encoding::UndefinedConversionError or other encoding issues when invoking Asciidoctor. To solve these problems, we recommend at least changing the active code page in your console to UTF-8.

chcp 65001

Once you make this change, all your Unicode headaches will be behind you.

Install Asciidoctor PDF

You can install Asciidoctor PDF using the gem install command. We’ll use this command to install the Asciidoctor PDF gem named asciidoctor-pdf that’s published on RubyGems.org. Pass the name of the gem to the gem install command as follows:

$ gem install asciidoctor-pdf

Installing Asciidoctor PDF will install a number of other gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk. For the most part, the versions of these dependencies are locked to the version of Asciidoctor PDF.

Install a prerelease or development version

To install the latest prerelease of the asciidoctor-pdf gem from RubyGems.org (if a prerelease is available), use the following command:

$ gem install asciidoctor-pdf --pre

You can also run the code from source if you want to use a development version or participate in development.

Installation troubleshooting

If you get a permission error while installing the gem, such as the one below, it’s likely you’re attempting to install the gem directly into your system. Installing gems for tech writing directly into your system is not recommended.

Permission error when attempting to install as a system gem

ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /Library/Ruby/Gems/2.x.x directory.

A better practice (and one that will ensure your sanity) is to ignore any version of Ruby installed on your system and use RVM to manage the Ruby installation instead. The benefit of this approach is that a) Ruby is guaranteed to be set up correctly, b) installing gems will in no way interfere with the operation of your system, and c) any bin scripts provided by the installed gems will be available on your PATH. All files are managed in user space (aka your home or user directory). If something gets messed up, you can simply remove the $HOME/.rvm folder and start over.

To learn how to install RVM, follow the RVM installation procedure covered in the Asciidoctor documentation. Once you have installed RVM, install a version of Ruby:

rvm install 3.1

Then switch to that version and set it as the default:

rvm use 3.1 --default

You only need to install the version of Ruby once. Each time you open a new terminal, be sure to select the default Ruby.

rvm use default

After installing the asciidoctor-pdf gem, you can see where it was installed using the following command:

$ gem which asciidoctor-pdf

To see where the bin script is located, use this command:

$ command -v asciidoctor-pdf

Both paths should be underneath the $HOME/.rvm directory. If not, check your RVM setup.

Optional dependencies

There are several optional features of this converter that require additional gems to be installed. Those features are as follows.

Source highlighting

You’ll need to install a syntax highlighter to use source highlighting (build-time only).

PDF optimization

If you want to optimize your PDF, you’ll need rghost or hexapdf. See Optimize the PDF for installation and usage instructions.

Automatic hyphenation

To turn on automatic hyphenation using the hyphens attribute, you’ll need to install the text-hyphen gem:

$ gem install text-hyphen

Accelerated image decoding

Ruby is not particularly fast at decoding images, and the image formats it supports are limited. To help, you can install prawn-gmagick, which delegates the work of decoding images to GraphicsMagick. Refer to Supporting additional image file formats for instructions about how to enable this integration.

The following table lists the optional dependencies of Asciidoctor PDF, including Asciidoctor extensions which are tested with this converter. The name of the dependency and its gem name are listed along with the minimum supported version and what feature or features it enables when installed (and, if necessary, required).

Minimum supported version of optional dependencies
Name / Gem	Minimum Version	Feature(s)
Asciidoctor Mathematical asciidoctor-mathematical	0.3.5	STEM support (must be required using `-r asciidoctor-mathematical`)
Asciidoctor Diagram asciidoctor-diagram	2.2.0	Diagram blocks (must be required using `-r asciidoctor-diagram`)
Rouge rouge	2.0.0	Syntax highlighting
Pygments (Ruby) pygments.rb	2.0.0	Syntax highlighting
Prawn Gmagick prawn-gmagick	0.0.9	Accelerates image embedding using GraphicsMagick
RGhost rghost	0.9.7	PDF optimization using Ghostscript (requires `optimize` attribute to be set)
Text Hyphen text-hyphen	1.4.1	Automatic hyphenation (requires `hyphens` attribute to be set)