Install Using Ruby Packaging
Using Ruby packaging entails making use of commands provided by Ruby (
bundle) to install gems.
A gem is a packaged Ruby application or library, often retrieved from RubyGems.org.
The benefit of using Ruby packaging to install Asciidoctor is that it’s universal. Provided you have configured Ruby correctly, Ruby packaging works the same way across all Ruby runtimes and operating systems. This page explains how to use Ruby packaging to install Asciidoctor from the asciidoctor gem.
Unless you’re running in a container (Docker, podman, OCI), never install gems using
The best way to ensure Ruby is configured to use Ruby packaging is to install Ruby using a Ruby version manager.
We recommend that you set up RVM and use it to install Ruby in your home directory (i.e., user space).
Once that is done, you can safely use the
bundle commands to install or update the Asciidoctor gem, or any other gem for that matter.
When using Ruby managed by RVM, gems are installed in a location isolated from the system (so you don’t need root/administrator access).
Once you’ve installed Ruby using RVM, and you have activated it using
rvm use 3.1, open a terminal and type:
$ gem install asciidoctor
If the gem installed successfully, Asciidoctor’s command line interface (CLI) will be available on your PATH. To confirm that Asciidoctor is available, execute:
$ asciidoctor --version
You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.
Asciidoctor 2.0.20 [https://asciidoctor.org] Runtime Environment (ruby 3.1.2p20 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
To install a prerelease version of Asciidoctor (e.g., a release candidate), include the
--pre option when running the
gem install command:
$ gem install asciidoctor --pre
--pre option will select the prerelease version of Asciidoctor instead of the latest stable version.
Note that it’s possible that the prerelease version is older than the latest stable version if no recent prerelease version is available.
Create a Gemfile in the root folder of your project (or the current directory):
$ bundle init
asciidoctorgem to the bottom of your Gemfile as follows:
gem 'asciidoctor' # or specify the version explicitly # gem 'asciidoctor', '2.0.20'
Save the Gemfile
Open a terminal and install the gem using:
To upgrade the gem, specify the new version in the Gemfile and run
bundle update (without specifying a gem) is not recommended as it will also update other gems, which may not be the desired result.
Once you install using Bundler, you must run any executables provided by the gems (e.g.,
You’re advised against using the
If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, you should use RVM to install Ruby in your home directory (i.e., user space).
Then, you can safely use the
You can upgrade Asciidoctor using the gem
$ gem update asciidoctor
If you accidentally use
$ gem cleanup asciidoctor
You can uninstall Asciidoctor using the gem
$ gem uninstall -x asciidoctor
-x option silences the confirmation to remove the
asciidoctor executable, instead removing it automatically.
In other words, it enables a complete uninstall.
If you have multiple versions of Asciidoctor installed, you will be prompted to specify which version you want to uninstall.
Select gem to uninstall: 1. asciidoctor-2.0.15 2. asciidoctor-2.0.16 3. All versions >
You can uninstall a specific version, or all versions.
Type one of the numbers at the prompt (
>) and press Enter.