Marc Busqué edited this page Jul 1, 2018 · 130 revisions
Clone this wiki locally

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 sane build environment.

  • macOS:

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

    # optional, but recommended:
    brew install openssl libyaml libffi
    # required for building Ruby <= 1.9.3-p0:
    brew tap homebrew/core && brew install apple-gcc42
  • Ubuntu/Debian/Mint:

    # Depending on your version of Ubuntu/Debian/Mint, libgdbm5 won't be available. In that case, try with libgdbm3.
    apt-get install autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev
  • CentOS/Fedora:

    # (`dnf install` on Fedora 22+) 
    yum install -y gcc-6 bzip2 openssl-devel libyaml-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-devel
  • openSUSE:

    zypper install -y gcc6 automake gdbm-devel libffi-devel libyaml-devel libopenssl-devel ncurses-devel readline-devel zlib-devel
  • Arch Linux:

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


GCC compatibility

As of this writing, Ruby may throw segmentation faults if built with gcc-7. Be sure to have a prior version of gcc installed, then specify it with the CC environment variable before building:

$ CC=/usr/bin/gcc-6 rbenv install 2.4.0


  • Ensure that there is no --user-install flag in your /etc/gemrc.

  • If compilation fails with a readline error, specify the location of libreadline.so in the with-readline-dir build flag. For example:

    $ RUBY_CONFIGURE_OPTS="--with-readline-dir=/usr/lib" rbenv install 2.4.0

    (Note that Ruby < 2.0 does not have the with-readline-dir flag; use with-opt-dir instead.)

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:

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


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 "/usr/include/openssl/asn1_mac.h:10:2: error: #error This file is obsolete; please update your software."

The openssl extension of Ruby version before 2.4 is not compatible with OpenSSL 1.1.x. At the moment, most Linux distributions that come with OpenSSL 1.1.0 have a separate package for OpenSSL 1.0.x.

On Debian 9 (stretch), it is libssl1.0-dev (note installing this would remove libssl-dev).

On Fedora 27, it is compat-openssl10-devel

On Arch Linux, it is extra/openssl-1.0 package, but it installs the library in non-standard locations. Specify PKG_CONFIG_PATH so that Ruby can find.

PKG_CONFIG_PATH=/usr/lib/openssl-1.0/pkgconfig \
  rbenv install 2.3.4

OpenSSL “SSLv3_method undeclared” error

On some systems, the provided OpenSSL library will be compiled without SSLv3 support. Ruby 2.2.3 installation will then fail with message:

error: ‘SSLv3_method’ undeclared here

The workaround is to apply this patch adapted from Ruby trunk:

curl -fsSL https://gist.github.com/mislav/055441129184a1512bb5.txt | \
  rbenv install --patch 2.2.3

For older Ruby versions like 1.9.3 the above patch will not work, use this instead:

curl -fsSL https://gist.github.com/FiveYellowMice/c50490693d47577cfe7e6ac9fc3bf6cf.txt | \
  rbenv install --patch 1.9.3-p551

OpenSSL bindings on Debian

Because of OpenSSL incompatibility in Debian (7.5 and above), Ruby might fail to compile without patching it first:

curl -fsSL https://github.com/ruby/ruby/commit/1e7a929c1d44d7a368fbe379211183ac6c972920.patch | \
  rbenv install --patch 1.9.3-p484

Make error for 2.0.0-p247 (and lower) on Fedora/Red Hat

make[2]: *** [ossl_pkey_ec.o] Error 1

This is a known issue with Ruby's openssl extension. The solution is to apply this patch:

curl -fsSL "https://github.com/ruby/ruby/commit/0d58bb55985e787364b0235e5e69278d0f0ad4b0.patch" | \
  filterdiff -x a/ChangeLog | rbenv install --patch 2.0.0-p247

Installing 2.0 on OS X 10.9 (Mavericks)

error: C compiler cannot create executables
- or -
fatal error: 'stdlib.h' file not found

You can try installing XCode Command Line tools to get GCC:

  1. xcode-select --install
  2. rbenv install 2.0.0-p247

Installing 1.8.7-p375 on OS X 10.11 (El Capitan)

  1. brew install apple-gcc42
  2. brew install https://github.com/Homebrew/homebrew-versions/raw/586b7e9012a3ed1f9df6c43d0483c65549349289/openssl098.rb
  3. RUBY_CONFIGURE_OPTS=--with-openssl-dir=/usr/local/opt/openssl098 ruby-build 1.8.7-p375

"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:

sudo mkdir -p /opt/rubies
sudo chown "${USER}:staff" /opt/rubies
rm -rf ~/.rbenv/versions                 # This will DELETE your existing Ruby versions!
ln -s /opt/rubies ~/.rbenv/versions

Now proceed as following:

ruby-build <version> /opt/rubies/<version>

1.8.7-p302 (and lower) segfaults for HTTPS requests on OS X 10.7+

Ruby 1.8.7 patchlevel 302 (and below, possibly above, including ruby enterprise edition) have a known compiler bug, however compiling Ruby will finish without errors. The bug will cause a segmentation fault whenever an SSL connection is opened, like .../timeout.rb:60: [BUG] Segmentation fault.

Try setting the following flags and recompiling Ruby:

CFLAGS="-O2 -fno-tree-dce -fno-optimize-sibling-calls" rbenv install 1.8.7-p302

Or somehow use gcc 4.6 or earlier instead.

Trouble with irb or pry

Try installing readline and recompiling Ruby.

  • Ubuntu: apt-get install libreadline-dev

  • Fedora: yum install readline-devel

  • macOS with Homebrew:

    brew install readline
    RUBY_CONFIGURE_OPTS=--with-readline-dir="$(brew --prefix readline)" rbenv install 1.9.3-p286

Missing zlib

cannot load such file -- zlib

Try installing zlib and recompiling Ruby.

  • Ubuntu: apt-get install zlib1g-dev
  • Fedora: yum install zlib-devel

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.

Missing psych for YAML with Ruby 2.1.0

On *BSD at runtime when you require "yaml" or try to use RubyGems:

It seems your ruby installation is missing psych (for YAML output).
Shared object "libyaml-0.so.2" not found, required by "psych.so"

If you can, try upgrading to Ruby 2.1.2 where this issue seems to be fixed. If you need to stay on the current version, however, you can work around the issue by setting LD_LIBRARY_PATH in your environment:

LD_LIBRARY_PATH="$(rbenv root)/versions/2.1.0/lib:$LD_LIBRARY_PATH" ruby ...

Build failure of fiddle with Ruby 2.2.0

If you use Debian, Ubuntu, try to install libffi-dev via apt-get.

$ apt-get install libffi-dev

CentOS, Fedora, try to install libffi-devel via yum.

$ yum install libffi-devel

or enabled --enable-shared option

$ RUBY_CONFIGURE_OPTS=--enable-shared rbenv install 2.2.0

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 on Gentoo

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.

Lower the number of parallel jobs

On hosts that report a large amount of CPU cores, but don't have plenty of RAM, you might get:

gcc: internal compiler error: Killed (program cc1)

The solution is to use MAKE_OPTS=-j2 to limit make to maximum of 2 parallel processes:

export MAKE_OPTS=-j2

or also with writable temp directory:

TMPDIR=~/tmp MAKE_OPTS=-j2 rbenv install 1.9.3-p327

Build error -Wno-packed-bitfield-compat

Newer versions of Ruby built with old version of gcc (less than 4.4.0) might result in an error:

cc1: error: unrecognized command line option "-Wno-packed-bitfield-compat"

A workaround is to apply the following patch:

curl -fsSL https://gist.github.com/ekr1/7313abef4348daa038dd.txt | \
  rbenv install --patch 2.2.3