Skip to content
Mislav Marohnić edited this page Sep 24, 2022 · 173 revisions

ruby-build is a tool that downloads and compiles various versions of Ruby. It is exposed as rbenv install through rbenv or simply as ruby-build when used standalone.

Suggested build environment

ruby-build will try its best to download and compile the wanted Ruby version, but sometimes compilation fails because of unmet system dependencies, or compilation succeeds but the new Ruby version exhibits weird failures at runtime. The following instructions are our recommendations for a reasonable build environment.


If you haven't done so, install Xcode Command Line Tools (xcode-select --install) and Homebrew.

For Ruby versions 2.x–3.0:

brew install openssl@1.1 readline libyaml
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.1)"

Ruby 3.1.x and above requires OpenSSL 3:

brew install openssl@3 readline libyaml
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@3)"

Using RUBY_CONFIGURE_OPTS to link to a specific OpenSSL installation like suggested above is not a strict requirement for installing Ruby on macOS, but it will speed up your Ruby installation and avoid any OpenSSL compilation issues.


apt-get install autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libgmp-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev uuid-dev

Depending on your OS version, libgdbm6 won't be available. In that case, try an earlier version, such as libgdbm5.


yum install -y gcc-6 patch bzip2 openssl-devel libyaml-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-devel


dnf install -y gcc patch make bzip2 openssl-devel libyaml-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-devel


pkg install devel/autoconf devel/bison devel/patch lang/gcc databases/gdbm devel/gmake devel/libffi textproc/libyaml devel/ncurses security/openssl devel/readline


zypper install -y gcc make patch automake bzip2 libopenssl-devel libyaml-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-devel

Arch Linux

pacman -S --needed base-devel libffi libyaml openssl zlib

If needed, install gcc6 from the AUR.

Updating ruby-build

If you have trouble installing a Ruby version, first try to update ruby-build to get the latest bug fixes and Ruby definitions.

First locate it on your system:

which ruby-build
ls "$(rbenv root)"/plugins

If it's in /usr/local/bin on a Mac, you've probably installed it via Homebrew:

brew upgrade ruby-build

Or, if you have it installed via git as an rbenv plugin:

git -C "$(rbenv root)"/plugins/ruby-build pull


For more troubleshooting tips, check the Discussions section.

Missing OpenSSL

The Ruby openssl extension was not compiled. Missing the OpenSSL lib?

You probably need to install openssl development headers:

  • Ubuntu: apt-get install libssl-dev
  • Fedora: yum install openssl-devel

MacPorts users may need to specify OpenSSL's location manually:

RUBY_CONFIGURE_OPTS=--with-openssl-dir=/opt/local rbenv install

OpenSSL version compatibility

Ruby < 2.4 is not compatible with OpenSSL 1.1.

When building Ruby 2.3 or older, you must ensure that OpenSSL 1.0 is available somewhere on the system and point to it via the --with-openssl-dir configure flag. At the moment, most Linux distributions that come with OpenSSL 1.1 have a separate package for OpenSSL 1.0.

For example:

# with Homebrew on macOS
brew install rbenv/tap/openssl@1.0
RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.0)" rbenv install 2.3.8

If an OpenSSL 1.0 package no longer exists for your distro, you can install a shared library from source by downloading a 1.0.x version of the source, unarchiving the files, then running the following from a terminal:

# cd into source directory you downloaded and unarchived
./config --prefix=/opt/openssl-1.0 shared
make test
sudo make install
RUBY_CONFIGURE_OPTS="--with-openssl-dir=/opt/openssl-1.0" rbenv install 2.3.8

In Arch-based Linux, this is done with a different option. See this Arch Wiki page.

OpenSSL does not come with CA certificates and Error during failsafe response: SSL_connect returned=1 errno=0 state=error: certificate verify failed will occur if you don't install the CA Certificates for OpenSSL 1.0.

With Ubuntu for example, you can install the ca-certificate package and link to the CA certificates

sudo apt install ca-certificates
rm -rf /opt/openssl-1.0/ssl/certs
ln -s /etc/ssl/certs /opt/openssl-1.0/ssl/certs

C compiler cannot create executables

There can be different causes of this error and none of them are usually immediately apparent. However, often the cause is that the build environment is incomplete or broken. Make sure you first follow the instructions in Suggested build environment.

Having the Anaconda set of Python tools is known to cause issues with building Ruby. The only know solution so far is to uninstall Anaconda.

mkdir: /Volumes/Macintosh: Not a directory

This can occur if you have more than one disk drive and your home directory is physically mounted on a volume that might have a space in its name, such as Macintosh HD:

$ df
/dev/disk2    ...  /
/dev/disk1s2  ...  /Volumes/Macintosh HD

The easiest solution is to avoid building a Ruby version to any path that has space characters in it. So instead of building into ~/.rbenv/versions/<version>, which is the default for rbenv install <version>, instead you could install into /opt/rubies/<version> and symlink /opt/rubies as ~/.rbenv/versions so rbenv continues to work as before.

Arch Linux default gem install path

WARNING:  You don't have ${HOME}/.gem/ruby/1.8/bin in your PATH,
          gem executables will not run.

The system Ruby creates the /etc/gemrc file which contains --user-install by default so that pacman-managed gems are not mixed up with externally installed gems. This setting affects the gem command in all Ruby versions, so all gems will get installed under ~/.gem instead of the default install path $(rbenv prefix)/lib/ruby/gems.

This is not a problem for ruby-build, but rbenv doesn't play well with --user-install, since it can't discover gem executables that were placed under ~/.gem.

No space left on device

Some distributions will mount a tmpfs partition with low disk space to /tmp, such as 250 MB. You can check this with:

mount | grep tmp
df -h | grep tmp

Compiling MRI requires at least 265 MB, so you should temporarily resize /tmp to allow more usage:

rm -rf /tmp/ruby-build*
mount -o remount,size=300M,noatime /tmp

Cannot load such file -- auto_gem

Gentoo defines a system-wide RUBYOPT environment variable that automatically wants to load auto_gem whenever any Ruby scripts gets executed. This will fail for Ruby versions other than the system one.

$ cat /etc/env.d/10rubygems

The solution is to configure your shell init script to export -n RUBYOPT (unexport) the value from your environment.

gcc: internal compiler error: Killed

Machines that report a large amount of CPU cores but not enough RAM might experience this error when compiling.

Use MAKE_OPTS to lower the number of parallel processes:

MAKE_OPTS=-j2 ruby-build ...

error: implicit declaration of function 'ffi_prep_closure' is invalid in C99 on recent macOS

Apple changed the default compilation flags of clang on later macOS which breaks compilation of older rubies.

To work around this you can disable some errors:

RUBY_CFLAGS='-Wno-error=implicit-function-declaration' ruby-build ...