A fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats.


Asciidoctor can be installed using (a) package managers for popular Linux distributions, (b) Homebrew for macOS, (c) the gem install command (recommended for Windows users), (d) the Asciidoctor Docker image, or (e) Bundler.

The benefit of using your operating system’s package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.

The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. Consult the package repository for your distribution to find out which version is packaged per distribution release.

To install the gem on Alpine Linux, open a terminal and type:

$ sudo apk add asciidoctor

To install the gem on Arch-based distributions, open a terminal and type:

$ sudo pacman -S asciidoctor

On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor. To install the package, open a terminal and type:

$ sudo apt-get install -y asciidoctor

On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor. To install the package, open a terminal and type:

$ sudo dnf install -y asciidoctor

You can use Homebrew, the macOS package manager, to install Asciidoctor. If you don’t have Homebrew on your computer, complete the installation instructions at brew.sh first. Once Homebrew is installed, you’re ready to install the asciidoctor gem. Open a terminal and type:

$ brew install asciidoctor

Homebrew installs the asciidoctor gem into an exclusive prefix that’s independent of system gems.

Before installing Asciidoctor using gem install, you should use RVM to install Ruby in your home directory (i.e., user space). Then, you can safely use the gem command to install or update the Asciidoctor gem. When using RVM, gems are installed in a location isolated from the system.

Open a terminal and type:

$ gem install asciidoctor

If you want to install a pre-release version (e.g., a release candidate), use:

$ gem install asciidoctor --pre

  1. Create a Gemfile in the root folder of your project (or the current directory)

  2. Add the asciidoctor gem to your Gemfile as follows:

    source 'https://rubygems.org'
    gem 'asciidoctor' 
  3. Save the Gemfile

  4. Open a terminal and install the gem using:

To upgrade the gem, specify the new version in the Gemfile and run bundle again. Using bundle update (without specifying a gem) is not recommended as it will also update other gems, which may not be the desired result.