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.
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.
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.
Once you make this change, all your Unicode headaches will be behind you.
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 (
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.
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.
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.
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.
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.
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
hyphensattribute, you’ll need to install the
$ 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).
|Library / gem name
STEM support (must be required using
Diagram blocks (must be required using
Accelerates image embedding using GraphicsMagick
PDF optimization using Ghostscript (requires
Automatic hyphenation (requires