Getting Started

Many developers meet Ruby without choosing it, because a tool they use is written in Ruby or configured with Ruby files. Those files are ordinary Ruby: knowing the language makes them readable and debuggable. Pages elsewhere on this site show them in real projects:

This section does not re-explain those files; it gives you the language underneath them.

Ruby is developed in the open. The ruby/ruby repository holds the interpreter, the core classes and the default gems, and the issue tracker at bugs.ruby-lang.org is where bugs, feature requests and design discussions live. A feature is proposed as a ticket with a use case, discussed there and in the core developers' meetings, and accepted or rejected by Matz; accepted features are implemented on the development branch and listed in the NEWS file of the next release. Ruby has shipped a new minor or major release every 25 December for years, with patch releases in between that carry only bug and security fixes. The cadence, the maintenance phases of each branch and the proposal process are described in Versions, Releases and Compatibility.

The community is spread over mailing lists, the Ruby Discord server, local user groups, blogs, newsletters and podcasts, and the ruby-lang.org community page keeps the current list. RubyKaigi, RubyConf and many regional conferences publish their talks, which rubyevents.org collects. Ruby Central is a non-profit organisation that supports the worldwide community and organises RubyConf.

Source: ruby-lang.org: Community

Do not use it for development. macOS still ships a Ruby, and it is very old:

Ruby 2.6 has been end-of-life since 2022, the macOS copy cannot run a modern gem or any Ruby 3 or 4 syntax (it does not know Data, endless methods, the it parameter or the hash shorthand {x:, y:}), and sudo gem install against it changes files that belong to the operating system. Many Linux distributions also package an old Ruby, and the official page warns that the packaged version may not be the newest one. Install your own Ruby with one of the routes below, and keep the system one for the system’s own scripts.

Source: ruby-lang.org: Installing Ruby

If you cannot or do not want to compile Ruby, use the package manager of your system. These are the commands the official installation page documents:

Source: ruby-lang.org: Installing Ruby

The winget identifier on that page is RubyInstallerTeam.Ruby.{MAJOR}.{MINOR}, and the page illustrates it with 3.2; substitute the release you want and run winget search RubyInstallerTeam.Ruby to list the available ones. Homebrew’s ruby formula currently provides Ruby 4.0.7, but on macOS the system /usr/bin/ruby still answers to ruby unless Homebrew’s bin directory comes before /usr/bin in your PATH; check with which ruby after installing. Package-manager Rubies install gems into system directories, so run gem install for your user (gem install --user-install) or, better, work inside Bundler so that you do not need to install gems globally at all (see RubyGems and Bundler).

On Windows, RubyInstaller is the usual choice. It is a community-maintained installer that is linked from ruby-lang.org. It comes in two flavours: the plain installer is enough for pure Ruby gems and for gems that ship precompiled binaries, and the "with DevKit" installer adds an MSYS2 and MinGW toolchain so that gems with C extensions can be compiled while they are installed. The installer also gives you the ridk command, which installs MSYS2 components and sets the environment for the development tools in the current shell. Windows 10 and 11 users can instead use the Windows Subsystem for Linux and follow the Linux instructions inside it, which is the closest match to the production environment of most Ruby applications.

Source: RubyInstaller for Windows

Installers compile or unpack one Ruby version into a directory of your choosing. Both are community tools.

ruby-build (from the rbenv project) works as a plugin for rbenv, where it provides the rbenv install command, or as the standalone ruby-build command:

Source: ruby-build

ruby-install (from the chruby author) installs into ~/.rubies/ for a normal user and into /opt/rubies/ for root, and takes the Ruby name and version as arguments:

Both compile Ruby, so you need the build dependencies of your platform first (a C compiler, make, and the development headers for OpenSSL, libyaml, zlib and readline are the usual list; both projects document the exact packages for each system). To build a Ruby with YJIT support from source you also need the Rust compiler; the YJIT guide states a minimum rustc version, and building ZJIT requires Rust 1.85.0 or later (see How Ruby runs a file).

Source: ruby-build, ruby-install

A version manager lets several Rubies coexist and selects one per shell or per directory. All of the following are community tools, listed (not endorsed) by ruby-lang.org. They differ in how they select a Ruby and what they change in your shell:

The commands you use daily are short in all of them. These are the documented forms for installing the newest 4.0 release and choosing it for the current project (the tools differ, so the commands are shown side by side rather than as one session):

Source: rbenv README, chruby README, asdf-ruby README, mise: Ruby, RVM: Installing RVM

The toolchain used to check this page is mise, which is why the outputs show its install paths. mise ls ruby and mise exec show the idea of a version manager in two lines: several Rubies are installed, and a command can be run with the one you name without changing anything else.

Source: mise: Ruby

Pick one version manager and uninstall the others, or disable their shell hooks. Two managers that both rewrite PATH produce the confusing situation where ruby -v and gem env disagree, and the first fix is always which -a ruby to see every candidate in PATH order.

A project records the Ruby it needs in a .ruby-version file, a one-line text file next to the code:

Source: rbenv README

Most managers read it (see the table above), and so do editors and CI actions. Bundler has its own, stricter declaration, the ruby line of the Gemfile, which makes bundle install fail on a different Ruby:

Source: Bundler: Gemfile

The two have different jobs: .ruby-version tells tools which Ruby to switch to, and the Gemfile line is a safety check that stops a mismatched install. A gemspec constrains Ruby with required_ruby_version, as the shelf gem does with ">= 4.0". All three are covered in Versions, Releases and Compatibility.

When nothing else works, download a tarball from ruby-lang.org, unpack it and build:

By default this installs under /usr/local; pass --prefix=DIR to ./configure to install elsewhere, for example into your home directory so that you do not need sudo. The official page notes that a Ruby built this way is not managed by any tool, which is why an installer or version manager is usually the better choice.

Source: ruby-lang.org: Installing Ruby

Ruby asks RubyGems where it keeps gems. gem env home is where gem install writes by default, and gem env gempath lists every directory searched. With a version manager the install directory belongs to your user, so you do not need sudo:

Source: RubyGems: Command reference

The directory name ends in 4.0.0 for every 4.0.x patch release: the library directory is versioned by ABI, not by patch. If gem install complains about permissions, that is the sign of a system Ruby; fix the Ruby you use instead of adding sudo.

ruby runs code from a file, from the command line or from standard input. These are the forms you will use first:

Source: Ruby command-line options

-e 'code' runs the string as a program, and may be repeated (the pieces are joined by newlines). With no file and no -e, Ruby reads the program from standard input, and __FILE__ is then -. A script receives the rest of the command line in the ARGV array, and $PROGRAM_NAME (also $0) holds its name.

The options you will meet in the first week:

Source: Ruby command-line options

ruby --help prints the same list, and the environment variables that change Ruby’s behaviour (RUBYOPT, RUBYLIB, RUBY_YJIT_ENABLE, GEM_HOME and others) are collected in Ruby Command Line and Environment. A few of the options in use, with real output:

Source: Ruby command-line options

(/private/tmp is macOS’s real path for /tmp.) A script also communicates through its exit status, which shells and CI systems read: 0 means success, 1 is what an uncaught exception or abort produces, and exit n returns your own code.

Source: Kernel#exit

irb is where you try things (see the next section), ri is the offline manual, gem manages libraries globally and bundle manages the libraries of one project. Their first commands:

Source: RubyGems: Command reference

RubyGems and Bundler share the version number 4.0.20 here because Ruby 4.0 bundles RubyGems 4 and Bundler 4. The Bundler guide describes the project workflow, and bundle init is its first command: it writes a starter Gemfile and nothing else.

Source: Bundler: bundle init

The full workflow (bundle install, the Gemfile.lock, bundle exec, groups, bundler/inline single-file scripts) is in RubyGems and Bundler.

Source: Ruby command-line options

The first line of a script may be a shebang that tells a Unix-like system which interpreter to use, which makes the file runnable as a command once it has execute permission. #!/usr/bin/env ruby finds the Ruby that is first on PATH, so it follows your version manager:

Source: Global variables

ARGV holds the command-line arguments as strings, ARGV.fetch(0, "reader") returns the first argument or a default (fetch with a default does not raise, unlike ARGV.fetch(0)), and "#{...}" interpolates the value of any expression into a double-quoted string. RuboCop’s Lint/ScriptPermission cop checks that a file with a shebang has the execute permission, which is the reason for the chmod. On Windows the shebang is ignored; you run ruby greet.rb or use the file association that RubyInstaller creates.

With the -x option Ruby skips everything before a #!ruby line, so a Ruby program can live inside another file, such as a shell script or an email:

Source: Ruby command-line options

__END__ ends the Ruby code of the file; whatever follows can be read through the DATA constant (see Program Structure and Lexical Elements).

A program that grows past one file splits into files that load each other. require_relative loads a file relative to the file that calls it, so it works whatever the current directory is:

The first file is app/lib/greeting.rb, the second app/main.rb. Run main.rb from inside its directory and from another directory:

Source: Kernel#require_relative

The tempting alternative, require "lib/greeting", does not do what it looks like. require with a bare name searches the load path, a list of directories, and the current directory is not on it:

Source: Kernel#require

-I. adds the current directory to the load path and the second run succeeds, but the file then works only when started from the right directory. Use require_relative for files of your own program and require for libraries and gems. The whole mechanism ($LOAD_PATH, $LOADED_FEATURES, load, autoload) is in Code Loading: require and autoload.

irb (Interactive Ruby) reads an expression, evaluates it and prints the result after =>. It is the fastest way to learn a method, test a regular expression or inspect an object. IRB 1.16, the bundled gem in Ruby 4.0.7, starts with the prompt irb(main):001>. The transcript below was made with irb --simple-prompt, which shortens the prompt to >>, so that it fits a page:

Source: IRB documentation

Three things in that transcript are worth noting. A line that prints something, like puts, shows the output and then => nil, because every expression has a value and puts returns nil. A string evaluates to itself, and the last value of a session is available as _. And the hash is printed in the Ruby 3.4 inspect format, {title: "ruby basics", pages: 120}, where the older one was {:title=>"ruby basics", :pages=>120}; it matters when you compare output with old tutorials. The real transcript printed a few more lines of backtrace under the error (paths inside the IRB gem), which are omitted above.

IRB has its own commands, listed by help. These are the ones to try first:

Source: IRB documentation

IRB is covered fully in IRB and Debugging, including binding.irb, which opens an IRB session inside a running program at that line.

ri shows the same documentation as docs.ruby-lang.org without leaving the terminal and without a network connection, in the format of the installed Ruby. Name a class, a method or both:

(The output continues with examples.) Array#sum names the instance method sum of Array, and Array.new would name a class method; this Class#method / Class.method convention is the one used in all Ruby documentation and error messages. ri -l lists every class and module that has documentation, ri --interactive starts a lookup prompt with completion, and --no-pager keeps the output in the terminal instead of a pager. Gems that ship RDoc documentation can be looked up the same way once their documentation has been generated.

Source: RDoc: ri

Source: Ruby in Twenty Minutes, Try Ruby, Ruby Playground

Source: NoMethodError

The first line is the exception site: the file, the line number and the method (here the top level, <main>), then the message and the exception class in parentheses. Three details of the format are new since Ruby 3.3 and 3.4, and older tutorials show the previous forms:

The blank line, the source line and the ^^^^^^ marker are added by error_highlight; the Did you mean? line is from did_you_mean. With the first, you can see that the call that failed was titel and not upcase in a long chain. error_highlight needs the source file to quote, so code given with -e gets no highlight (compare the -e outputs earlier on this page).

Source: DidYouMean and ErrorHighlight

Source: DidYouMean, Hash#fetch

did_you_mean handles NameError (misspelled constants, local variables, instance and class variables), NoMethodError, KeyError (for Hash#fetch and friends), LoadError for require paths and a few more. The lines that begin with from are the backtrace: the first line is where the exception was raised (here inside Hash#fetch) and each from line is a caller, innermost first. In the KeyError case the interpreter frame of fetch comes first because the error is raised inside it, and the call in your code comes next.

Source: ErrorHighlight

For ArgumentError and TypeError, error_highlight points at the call (the "caller") rather than at the method that raised, which is the part you can fix. The annotation is produced by Exception#detailed_message (Ruby 3.2), the method that formats the message together with extra detail such as the highlight; Exception#message itself stays free of it, which is what you want when you log or compare messages. If an annotation gets in your way, turn the gems off: ruby --disable-error_highlight and ruby --disable-did_you_mean (also RUBYOPT=--disable-did_you_mean):

Source: Exception#detailed_message

Source: Kernel#Integer

The exception hierarchy, raise, rescue and the full list of built-in errors are in Exceptions and Error Handling.

Ruby also warns about code that is legal but suspicious. Warnings go to standard error, do not stop the program, and depend on the -W level. -w turns on the verbose level, which adds checks such as unused variables:

Source: Ruby command-line options, Warning

The second command shows a chilled string: since Ruby 3.4 a string literal in a file without the magic comment can still be modified, but Ruby marks it, and with the deprecated category enabled it warns on the first modification. The warning is off by default, which is why most code does not notice it; the day string literals become frozen by default, that code will raise FrozenError. Chilled strings are developed in Literals, and warning categories, Warning[] and Kernel#warn in Versions, Releases and Compatibility.

Syntax errors are different: they are found before any line of the program runs. Ruby 3.4 and later print them with Prism’s format, which shows the lines around the problem and marks the exact position. A file that opens an if and never closes it:

Source: SyntaxError

Notice that neither of the first two puts printed anything: Ruby parses and compiles the entire file first, and only then runs it (more in How Ruby runs a file). The first block, "Unmatched keyword, missing end' ?", is produced by `syntax_suggest, a default gem that is loaded when a SyntaxError comes from a file and that points at the indentation block that does not balance. It is the quickest way to find a missing end in a long file. The second block is the parser’s own diagnostic. To check a file without running it, use ruby -c, which prints only the parser’s part:

Source: Ruby command-line options

ruby -wc file.rb (check syntax, with warnings) is what every example on this page passes, and it is the cheapest check to put in an editor on save or in a pre-commit hook.

A JIT compiler turns frequently executed methods into machine code while the program runs. Ruby 4.0 includes two:

Source: YJIT, ZJIT, NEWS for Ruby 4.0.0

The previous JITs, MJIT and RJIT, are gone: MJIT was removed in Ruby 3.3 and the --rjit option in Ruby 4.0. Tuning, statistics and when a JIT helps are in YJIT, ZJIT and the VM.

Ruby frees memory for you. The default collector is a generational, incremental mark-and-sweep collector, it can move objects to reduce fragmentation (GC.compact), and it runs when the heap needs room, not at a time you choose. As a beginner you only need to know that you do not free objects yourself, and that holding references (in a global, a constant, a cache) keeps objects alive. GC.stat and ObjectSpace let you look, and Garbage Collection and Memory covers them.

Source: GC