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, you’ll need a Ruby runtime to run it.

The Ruby versions on which Asciidoctor PDF is supported and tested are Ruby 2.7 or greater or JRuby 9.2 or greater. We always recommend using the most recent version of Ruby or JRuby, if possible. If you attempt to use an unsupported version of Ruby with Asciidoctor PDF, the conversion will likely fail in unexpected ways.

All required libraries (i.e., gems) will be installed automatically when you install Asciidoctor PDF, which is covered in the next section. You must install any optional dependencies yourself in order to activate the corresponding optional features.

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 at least 2.7 (or a JRuby version that starts with at least 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.

See the system encoding requirements section to learn how to override the default character encodings when using Asciidoctor if you can’t modify your system encoding.

Install Asciidoctor PDF

Asciidoctor PDF (gem: asciidoctor-pdf, command: asciidoctor-pdf) is published as a RubyGem to the rubygems.org software registry. You install Asciidoctor PDF from that registry using the RubyGem management tools provided by Ruby (bundle or gem). Alternately, you can build and install Asciidoctor PDF from source.

Refer to the table below for instructions on how to install Asciidoctor PDF. If you use Bundler to manage your gems in a Gemfile, add the entry listed in the Bundler column. Otherwise, run the command in the gem command column.

Library gem name Bundler gem command

Asciidoctor PDF

asciidoctor-pdf

gem 'asciidoctor-pdf'
gem install asciidoctor-pdf

Installing Asciidoctor PDF will automatically install a number of additional gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk. The versions of these required 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
Library / gem name 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)

Asciidoctor Kroki
asciidoctor-kroki

0.8.0

Diagram blocks (must be required using -r asciidoctor-kroki)

Rouge
rouge

2.0.0

Syntax highlighting

Pygments (Ruby)
pygments.rb

2.0.0

Syntax highlighting

CodeRay
coderay

1.1.0

Syntax highlighting

Prawn Gmagick
prawn-gmagick

0.0.9

Accelerates image embedding using GraphicsMagick

RGhost
rghost

0.9.7
(avoid 0.9.8)

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)