Codectionary / Developer documentation / Ruby

Check the macOS Ruby, install an independently managed version with rbenv and run a Ruby program without changing system files.

Check the Ruby already on your Mac

Open Terminal and run ruby --version and command -v ruby. Some macOS installations include a Ruby managed by Apple. It may be older than the version your project needs, and macOS can change or protect it. Seeing a version number does not mean it is the best Ruby for development.

Leave the system Ruby and its permissions alone. For development, a version manager installs a separate Ruby in your user account and lets a project select the version it needs. This avoids relying on sudo gem install or modifying /usr/bin/ruby.

Terminal — inspect the current Ruby

ruby --version
command -v ruby

Select a supported Ruby version

Use Ruby’s official branch-status page to choose a maintained stable release. If you are joining an existing project, follow its documented Ruby version and dependency requirements. Preview and end-of-life releases are poor defaults for a new beginner project. Ruby version numbers change over time, so replace X.Y.Z below with the actual maintained version you selected.

rbenv is one version-manager option documented by its maintainers. It selects which installed Ruby a shell or project uses; ruby-build supplies the install command that compiles a Ruby release. Homebrew is a macOS package manager used here to install those tools, not a replacement for the Ruby language.

Install rbenv and a project Ruby

If Homebrew is not installed, follow its official installation instructions first. Install the version manager and ruby-build with Homebrew. Run rbenv init and follow its shell setup instructions, then close and reopen Terminal. List available releases and replace X.Y.Z in the following commands with your chosen version before running them. The rbenv global setting selects a default for your user; rbenv local X.Y.Z inside a project folder selects that version only for that project.

A source build may need Apple’s Command Line Tools. If the compiler is missing, run xcode-select --install and follow the macOS prompt. For missing libraries such as OpenSSL or libyaml, use ruby-build’s current build-environment guidance rather than changing system library files.

Terminal — install the version manager

brew install rbenv ruby-build
rbenv init

Terminal — after restarting the shell; replace X.Y.Z first

rbenv install -l
rbenv install X.Y.Z
rbenv global X.Y.Z

Confirm the selected Ruby

Run ruby --version, gem --version and rbenv which ruby. The last command shows the installed Ruby executable chosen by rbenv. If command -v ruby still points to the system Ruby, reopen the shell and check the output of rbenv init and your shell startup configuration before installing anything again.

Avoid running gems with sudo to work around a permissions error. First confirm that rbenv has selected your own Ruby rather than the OS-managed one.

Terminal — verify the development Ruby

ruby --version
gem --version
rbenv which ruby
command -v ruby

Run a Ruby file

Save the line below in a plain-text file named hello.rb. In Terminal, change to its folder and run ruby hello.rb. The .rb file contains source code, and puts prints Hello, Codectionary! with a newline. No Rails project or package installation is required.

If Terminal reports that it cannot find hello.rb, inspect your current folder with pwd and list the files with ls. If the code produces a syntax error, make sure the quotation marks are ordinary straight quotes.

hello.rb

puts "Hello, Codectionary!"

Terminal — run the script

ruby hello.rb

PATH, permissions and build errors

A PATH problem means the shell is calling a different Ruby than rbenv selected; use rbenv which ruby and command -v ruby to compare them, then complete rbenv’s shell initialization. A permissions error during gem installation often means you are still using the OS-managed Ruby. Do not change ownership of system Ruby directories or use sudo as a blanket fix.

If rbenv install fails while compiling, inspect the error near the end of its build log. Check Command Line Tools and the ruby-build suggested build environment for your macOS release and selected Ruby. An older Ruby release may also be incompatible with a newer toolchain; prefer a maintained release unless your project explicitly requires an older one.

Syntax

ruby --version
ruby hello.rb

Examples

Run a macOS Ruby script

Save as hello.rb and run ruby hello.rb in Terminal.

puts "Hello, Codectionary!"
  1. The .rb file holds Ruby source code.
  2. puts prints the String argument; Ruby allows this simple method call without parentheses.
  3. The terminal displays Hello, Codectionary! after the selected Ruby runs the file.

Best practices

  • Use a maintained Ruby version compatible with your project.
  • Keep macOS-managed Ruby and system directories intact.
  • Check which Ruby your shell selected before troubleshooting gem permissions.

Runtime & versions

Ruby interpreter. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

Ruby documentation

Specifications & further reading