'\" t
.\"     Title: ruby-build
.\"    Author: Mislav Marohnić
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-05-07
.\"    Manual: ruby-build Manual
.\"    Source: ruby-build 20260520
.\"  Language: English
.\"
.TH "RUBY\-BUILD" "1" "2026-05-07" "ruby\-build 20260520" "ruby\-build Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
ruby-build \- Download, compile, and install a version of Ruby
.SH "SYNOPSIS"
.sp
ruby\-build [\-dvpk] \fI<definition>\fP \fI<prefix>\fP [\-\- \fI<configure\-args>\fP.\|.\|.]
.br
ruby\-build {\-\-list|\-\-definitions}
.br
ruby\-build \-\-resolve \fI<version>\fP
.br
ruby\-build \-\-version
.SH "DESCRIPTION"
.sp
ruby\-build downloads, compiles, and installs a Ruby version named by the
\fIdefinition\fP argument into the location specified by \fIprefix\fP.
.sp
The \fIdefinition\fP argument can be a path to a file on disk, in which case
it is sourced into ruby\-build as a bash script.
.sp
Optionally, extra Ruby \fIconfigure\-args\fP may be listed after "\-\-" and
will get forwarded to the \f(CR./configure\fP invocation.
.sp
By default, all compile output is redirected to a log file at
\f(CR$TMPDIR/ruby\-build.*.log\fP. Activate the verbose mode to skip the log file
and print everything to standard streams.
.SH "RUBY VERSIONS"
.sp
When listing "latest" Ruby versions, such as in \f(CR\-\-list\fP output,
ruby\-build only knows of Ruby versions that are bundled with this project.
That means that when a new Ruby version comes out, ruby\-build will not
know about it immediately; you will have to upgrade ruby\-build before you
can use it to install the new Ruby version.
.SH "RUBY IMPLEMENTATIONS"
.sp
ruby\-build ships with definitions for the following Ruby implementations:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
CRuby, also known as "MRI": denoted by version numbers in form of "X.Y.Z".
This is the main Ruby implementation that most people use.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
"jruby": High\-performance Ruby implementation with real threading built
on top of the Java virtual machine (JVM).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
"mruby": Lightweight Ruby for microcontrollers.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
"picoruby": Alternative mruby implementation for one\-chip microcontrollers.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
"truffleruby": The Native standalone distribution of TruffleRuby, an
implementation of Ruby on top of GraalVM\(cqs Truffle framework.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
"truffleruby+graalvm": The JVM standalone distribution of TruffleRuby.
.RE
.sp
The \fIdefinition\fP argument may optionally start with "ruby\-", in which case
it resolves to a CRuby that matches the version number that follows. The
\fIdefinition\fP argument may also be a name of one of the alternative Ruby
implementations, in which case the latest version of that implementation
will be installed.
.SH "OPTIONS"
.sp
\fB\-l, \-\-list\fP
.RS 4
List latest stable releases for each Ruby
.RE
.sp
\fB\-\-definitions\fP
.RS 4
List all local definitions, including outdated ones
.RE
.sp
\fB\-\-resolve\fP
.RS 4
Print the definition name of the latest stable Ruby version matching the \fIversion\fP argument
.RE
.sp
\fB\-\-version\fP
.RS 4
Show version of ruby\-build
.RE
.sp
\fB\-d, \-\-dir\fP
.RS 4
Install the Ruby in the \fIprefix/definition\fP destination instead of directly in \fIprefix\fP
.RE
.sp
\fB\-v, \-\-verbose\fP
.RS 4
Verbose mode: forward all build output to stdout/stderr
.RE
.sp
\fB\-p, \-\-patch\fP
.RS 4
Apply a patch from stdin before building
.RE
.sp
\fB\-k, \-\-keep\fP
.RS 4
Do not remove source tree after installation
.RE
.sp
\fB\-4, \-\-ipv4\fP
.RS 4
Resolve names to IPv4 addresses only
.RE
.sp
\fB\-6, \-\-ipv6\fP
.RS 4
Resolve names to IPv6 addresses only
.RE
.SH "EXAMPLES"
.sp
Install a Ruby version while tweaking some configuration options:
.sp
.if n .RS 4
.nf
.fam C
$ ruby\-build 3.4.9 /path/to/destination \-\- \-\-disable\-install\-doc \-\-with\-openssl\-dir=/opt/openssl
.fam
.fi
.if n .RE
.sp
Install a Ruby version to \f(CR~/.rubies/ruby\-3.4.9\fP:
.sp
.if n .RS 4
.nf
.fam C
$ ruby\-build \-\-dir ruby\-3.4.9 ~/.rubies
.fam
.fi
.if n .RE
.sp
Install the latest Ruby 3.x version to \f(CR~/.rubies/ruby\-3.x.y\fP:
.sp
.if n .RS 4
.nf
.fam C
$ ruby\-build \-\-dir ruby\-3 ~/.rubies
.fam
.fi
.if n .RE
.sp
Install a Ruby version to \f(CR~/.rbenv/versions/3.3.11\fP:
.sp
.if n .RS 4
.nf
.fam C
$ ruby\-build \-\-dir 3.3.11 ~/.rbenv/versions
.fam
.fi
.if n .RE
.sp
Usage as rbenv plugin, accomplishes the same as the previous example:
.sp
.if n .RS 4
.nf
.fam C
$ rbenv install 3.3.11
.fam
.fi
.if n .RE
.SH "ENVIRONMENT VARIABLES"
.sp
\fBTMPDIR\fP
.RS 4
The location to write temporary files on disk
.RE
.sp
\fBRUBY_BUILD_BUILD_PATH\fP (default: a timestamped subdirectory of \fITMPDIR\fP)
.RS 4
The build location for downloading source files to and compiling
.RE
.sp
\fBRUBY_BUILD_CACHE_PATH\fP (default: "~/.rbenv/cache" if invoked as rbenv plugin)
.RS 4
Where to cache downloaded package files
.RE
.sp
\fBRUBY_BUILD_HTTP_CLIENT\fP (default: first tool found in PATH)
.RS 4
One of "aria2c", "curl", or "wget" to use for downloading
.RE
.sp
\fBRUBY_BUILD_ARIA2_OPTS\fP
.RS 4
Additional options to pass to aria2c for downloading
.RE
.sp
\fBRUBY_BUILD_CURL_OPTS\fP
.RS 4
Additional options to pass to curl for downloading
.RE
.sp
\fBRUBY_BUILD_WGET_OPTS\fP
.RS 4
Additional options to pass to wget for downloading
.RE
.sp
\fBRUBY_BUILD_MIRROR_URL\fP (default: a sponsored Amazon CloudFront mirror)
.RS 4
Custom mirror URL root to download packages from
.RE
.sp
\fBRUBY_BUILD_MIRROR_PACKAGE_URL\fP
.RS 4
Custom complete mirror URL
.RE
.sp
\fBRUBY_BUILD_SKIP_MIRROR\fP
.RS 4
Bypass the download mirror and fetch all package files from their original URLs
.RE
.sp
\fBRUBY_BUILD_ROOT\fP (default: "share/ruby\-build" within ruby\-build install location)
.RS 4
Custom build definition directory
.RE
.sp
\fBRUBY_BUILD_TARBALL_OVERRIDE\fP
.RS 4
Override the URL to fetch the ruby tarball from, optionally followed by "#<checksum>"
.RE
.sp
\fBRUBY_BUILD_DEFINITIONS\fP
.RS 4
Paths to search for build definitions in addition to \fIRUBY_BUILD_ROOT\fP
.RE
.sp
\fBCC\fP
.RS 4
Path to the C compiler
.RE
.sp
\fBRUBY_CFLAGS\fP
.RS 4
Additional \f(CRCFLAGS\fP options to use for Ruby compilation
.RE
.sp
\fBCONFIGURE_OPTS\fP
.RS 4
Additional "./configure" arguments
.RE
.sp
\fBMAKE\fP (default: "make")
.RS 4
Custom make command (e.g., "gmake")
.RE
.sp
\fBMAKE_OPTS\fP, \fBMAKEOPTS\fP
.RS 4
Additional arguments for "make"
.RE
.sp
\fBMAKE_INSTALL_OPTS\fP
.RS 4
Additional arguments for "make install"
.RE
.sp
\fBRUBY_CONFIGURE_OPTS\fP
.RS 4
Additional "./configure" arguments that apply only to Ruby source
.RE
.sp
\fBRUBY_MAKE_OPTS\fP
.RS 4
Additional make arguments that apply only to Ruby source
.RE
.sp
\fBRUBY_MAKE_INSTALL_OPTS\fP
.RS 4
Additional "make install" arguments that apply only to Ruby source
.RE
.sp
\fBNO_COLOR\fP (default: allow colors when connected to terminal)
.RS 4
Disable ANSI colors in output
.RE
.sp
\fBCLICOLOR_FORCE\fP
.RS 4
Use ANSI colors in output even when not connected to a terminal
.RE
.SH "NOTES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
.URL "https://github.com/rbenv/ruby\-build#readme" "" ""
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
.URL "https://github.com/rbenv/ruby\-build/wiki" "" ""
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
.URL "https://github.com/rbenv/ruby\-build/discussions" "" ""
.RE
.SH "AUTHOR"
.sp
Mislav Marohnić