Easiest Way To Install Ruby On Mac In 2024

Supported macOS versions

• Sonoma (macOS 14)
• Ventura (macOS 13)
• Monterey (macOS 12)

Now let’s talk about the few things you need to consider before starting the installation process.

Make sure your computer is plugged in and has a stable internet connection

The Mac cleanup and installation preparation will take 15 minutes if you follow step-by-step instructions. Make sure your machine doesn’t go to sleep mode while installing the various tools. Also, using VPN or a slow shared public WiFi is a big NO. Rather, using a mobile hotspot connection will be a better option than public WiFi.

Make sure you can connect this Github Page once you’re connected to the internet connection.

You must know there are certain internet and mobile service providers, such as ACT in India that may block access to the above-mentioned GitHub domain. If you experience any such issue, you can connect with the MeisterIT Systems iOS development team to get it fixed for you!

If you’re running Ventura or a later version:

• Click on the Apple icon located at the top left of your Mac, and click System settings.
• Choose “Displays” from the left sidebar.
• Click on the “Advanced Button.” You can see it by adjusting the window size by dragging its bottom edge.
• In the “Battery & Energy” section at the bottom ensure that “Prevent automatic sleep on power adapter when the display is off” is enabled.
• Click “Done” to save the changes.

If you’re using Monterey or an earlier version:

• Click on the Apple icon at the top left of your Mac, and select System settings.
• Choose “Battery” from the options.
• Select “Power Adapter” from the left sidebar.
• Activate the option to “Prevent your Mac from automatically sleeping when the display is off.”

Ensure you’ve the latest macOS operating system

Before proceeding, verify that you have installed all available Apple software updates for your existing macOS version. To do this, click on the Apple icon located in the top left corner of your screen, then select System Settings, followed by Software Update. If any updates are listed, proceed to install them. If your current macOS version is already up to date, there’s no need to upgrade to the latest macOS version.

Ensure Homebrew is set up for brewing

If you haven’t attempted to install Homebrew yet, skip the segment. To confirm, inspect the contents of the /usr/local directory by executing this command in the Terminal app:

If the folder is empty, Homebrew isn’t installed.

If your Mac is equipped with the Apple Silicon chip (M1/M2), you also need to examine the /opt/homebrew directory:

If these directories aren’t empty, Homebrew is installed. You must ensure that it’s of the latest version by executing the following command:

The output should be Your system is ready to brew upon completion.

If Homebrew isn’t prepared for brewing, review the feedback provided by Homebrew and attempt to resolve any issues or seek assistance through Homebrew Discussions. Homebrew gives detailed instructions to fix issues. You can also avoid fixing the warnings or errors as in most cases they may not impact Ruby installation. However, the tutorial might still function in the rest of the cases, but there is no guarantee.

Suppose your /usr/local folder isn’t empty on an Apple Silicon Mac. In that case, it suggests Homebrew is installed with Rosetta, via arch -x86_64 in the terminal, or through transferring files from an Intel Mac to an Apple Silicon Mac. This scenario can lead to various complications, potentially causing errors during the installation, running bundle install or pod install in your projects.

Make sure you’ve installed Chruby instead of RVM, rbenv, asdf, or frum

To ensure smooth Ruby management, it’s best to avoid conflicts between different Ruby managers. Therefore, we advise against having RVM, rbenv, asdf, or frum installed alongside chruby, which we recommend due to its simplicity and efficient Ruby switching capabilities. So, if you’ve RVM, rbenv, asdf, or frum installed on your Mac, we recommend uninstalling them.

• If you opt for Ruby on Mac Prime, it automatically handles the removal of these conflicting version managers.

To verify if any other Ruby managers are present, execute the following commands in your terminal:

If the execution of those commands yields any information, it indicates that you have that particular tool installed. Refer to the respective website or GitHub repository for uninstallation instructions.

If you receive a “command not found” response, probably, the tool is not installed on your system. However, there can be a case that the tool is installed but not within your PATH. If you’re unfamiliar with the term PATH, you can visit the guide to gain insight into it. Understanding PATH will enable you to troubleshoot development setup issues with greater confidence.

Ensure Ruby is Not Installed via Homebrew

By default, Ruby on Mac is managed automatically, but it’s essential to verify that it’s not installed via Homebrew to avoid potential issues. Run this command to find out which all tools are installed with Homerbrew:

You can narrow down the list to find out which contains the string “ruby” with this command.

If Ruby is not visible in the list (it might also appear as ruby@ followed by the version, such as ruby@3.2), it indicates that it’s not installed. Conversely, if Ruby is present, uninstall it using the following method:

If it’s a specific version, you can uninstall it via this command:

Next, navigate to either~/.zshrc or ~/.bash_profile (refer to the Notes on your shell section), and delete any mentions of Homebrew Ruby. Homebrew typically installs items in either /opt/homebrew or /usr/local. Remove any lines directing to Homebrew directories that also include “ruby”, such as/opt/homebrew/opt/ruby.

Check out you don’t have Cocoapods installed with Homebrew

To avoid potential complications, ensure that Cocoapods is not installed via Homebrew. Having multiple Cocoapods installations can often lead to difficulties, particularly for individuals working with React Native, Flutter, or similar projects reliant on Cocoapods. It is advisable to adopt a consistent installation approach by using gem install cocoapods once you have established a suitable Ruby development environment.

Employ the identical methodology as described in the preceding section to ascertain whether Cocoapods have been installed via Homebrew. If such an installation is detected, it is recommended to uninstall it promptly.

Your macOS username and home folder shouldn’t have space in their name

Additionally, ensure that your macOS username and home folder do not contain spaces in their names. Although Apple typically prohibits the creation of macOS usernames with spaces, rare scenarios may lead to this occurrence. Having spaces in the home folder name can introduce various complications. To address this issue, carefully follow Apple’s instructions.

Do you have enough free disk space?

Furthermore, confirm that you have sufficient free disk space available. While Apple’s standalone Xcode command line tools typically occupy around 5GB of disk space, the installer may require more space on your hard drive, usually approximately 15GB. As a general rule, it is recommended to maintain at least 10% of your total hard drive capacity as free space.

Installation

What if you’re using an Apple Silicon Mac (M1/M2)

If this is the case, you need to ensure that Terminal is not in Rosetta mode. You can do it by running a command in Terminal:

If your Mac is powered by Apple Silicon, the output of uname -m should indicate arm64. However, if your machine is operating in Rosetta mode then it will display x86_64.

Here’s how to disable it:

• Quit Terminal/iTerm/ any other terminal application if it’s running.
• Navigate to the Finder.
• Locate your terminal application. For the default Apple Terminal app, access the Utilities folder by pressing shift-command-U (alternatively, choose “Go” from the menu bar, then click on “Utilities”).
• Select the Terminal app by clicking once on it, but refrain from launching it.
• Press the keyboard shortcut ⌘-i to open the Info window (or from the menu bar, select “File”, then “Get Info”).
• Uncheck the checkbox labelled “Open using Rosetta”.
• Close the Terminal Info window.
• Launch Terminal/iTerm or any other preferred terminal application.
• Run uname -m again. It should now indicate arm64, confirming that Rosetta mode has been deactivated. You can now proceed with the subsequent steps outlined in this guide.
• Additionally, run arch. The output should also display arm64.

If either uname -m or arch commands fail to indicate arm64, it suggests that another factor is enabling Rosetta mode. Review the following files for any references to arch -x86_64, i386, ARCHFLAGS, or any lines that seem to configure the Intel architecture:

• ~/.zshrc
• ~/.zprofile
• ~/.zlogin
• ~/.bash_profile
• ~/.profile
• ~/.bashrc
• ~/.config/fish/config.fish

Remove or comment out any such lines found in these files. Afterwards, quit and restart your terminal application, then recheck the output of uname -m.

If the output still displays x86_64, then it’s necessary to perform a comprehensive cleanup of your development environment and start anew.

Notes on your shell

In this guide, we assume you’re using zsh. However, if you’re unsure about it, you must find out which shells you’re using. Also, replace references to .zshrc with .bash_profile if you’re using Bash.

Step 1: Installing Homebrew and Command Line Tools

Homebrew, also known as “the missing package manager for macOS,” simplifies the installation of numerous open-source tools. While detailed installation instructions are available in the Homebrew Documentation, typically, you only need to execute the command provided at the top of the Homebrew site:

Please note that the commands listed on the Homebrew site may vary. Copy and paste the command into your Terminal window, press return, and carefully follow any prompts that appear in the Terminal. For instance, Homebrew may request your macOS password.

Homebrew automatically installs the Apple Command Line Tools, usually in the background. However, if this process changes, remain attentive to any windows that require your input.

After a successful installation, quit and restart the Terminal. Then, verify if Homebrew is ready to use by running:

If the output indicates “Your system is ready to brew,” proceed to Step 2. Otherwise, carefully read any instructions provided by Homebrew. They typically offer helpful guidance to resolve any issues.
For Apple Silicon Macs, Homebrew may recommend running additional commands post-installation, such as:

Ensure to execute these commands as instructed.

Quit and restart the Terminal once more and confirm if everything is functioning correctly.

This step ensures that Homebrew and associated components are properly configured.

Step 2: Install chruby and the latest Ruby with ruby-instal

To install chruby and ruby-install, run this command:

Then install the latest Ruby (currently 3.3.0):

Ensuring you can install the most recent version of Ruby is crucial before attempting to install alternative Ruby versions.

This process may require a few minutes. Upon successful installation, proceed to the next phase of configuring your shell to utilize chruby automatically.

However, if the installation fails with messages such as !!! Compiling Ruby 3.3.0 failed!, !!! Installation of ruby 3.3.0 failed!, !!! Configuration of ruby 3.3.0 failed!, or any similar error, it’s probable that there’s an issue with your development environment setup.

What should you do if Ruby Installation fails?

If Ruby installation fails, it indicates potential interference from elements within your system. A clean development environment is essential for the latest Ruby to function correctly. Various factors can affect Ruby installation on macOS, including:

• macOS version
• Xcode/Command Line Tools version
• Intel vs. Apple Silicon
• Concurrent installation methods with and without Rosetta
• Version manager employed
• Active Ruby version
• Specific Ruby version
• Incompatible tools installed simultaneously
• Missing, misconfigured, or outdated development tools

Resolving installation issues typically involves cleaning up your development environment and starting from scratch, which may entail numerous steps and considerable time. While alternative solutions may exist depending on your circumstances, many online fixes are temporary workarounds that could introduce further complications.

Attempting to install older Ruby versions may also encounter failures due to varying settings and tool requirements based on factors like the Ruby version, Mac model, macOS version, and Xcode/Command Line Tools version.

Configure your shell

You can configure the shell with these steps:

The next step is to Quit and relaunch Terminal, and ensure that everything is working:

Your version should match the version you installed in Step 2.

Step 3: Install a gem

Your Ruby development environment is now operational. You can now install Rails, Jekyll, Cocoapods, Fastlane, Bundler, Compass, or any other gem you’ve been attempting to install over the past days or months! However, make sure to refrain from using sudo while installing any of these gems.

You can securely install gems using the command gem install followed by the name of the desired gem.

Keep in mind that certain gems may not be compatible with Apple Silicon (M1/M2) processors. Keep this in mind and use more contemporary alternatives or try reaching out to the maintainers to inquire about updates.

Tips to install different versions of Ruby and Switch Between Them

If you want to install an additional Ruby version, initiate the process by executing “ruby-install” followed by your desired version. However, prior to this, make sure which version of Apple Command Line Tools (CLT) or Xcode you’ve running on your machine.

You can do it by running this command into your terminal.

Look for the lines at the bottom starting with CLT: and Xcode:. If either begins with 14 or higher, and you intend to install a version older than 3.1.3, 3.0.5, or 2.7.7 (excluding 2.6.x or earlier), follow this installation format:

Alternatively, if your CLT/Xcode version is less than 14, proceed with a standard Ruby installation without any additional options:

After installing the desired version, switch to it by quitting and restarting your terminal. Once done, execute “chruby” followed by the version number, as shown below:

It’s important to note that chruby differs from other Ruby version managers in its inability. So you shouldn’t set a “global” Ruby version that’s universally available. If you’ve followed this guide, everytime you open a Terminal Chruby will switch to the default version Ruby 3.3.0 or the latest version specified in your shell file. This enables you to install gems globally within the designated Ruby version using h gem install name_of_gem.

However, if it appears in a different directory that doesn’t have .ruby-version file, or if the .ruby-version file is set to a Ruby version that Chruby doesn’t know about, it will revert to the system Ruby, typically version 2.6.10 on macOS Monterey and higher (Ventura or Sonoma.)

Avoid using the system Ruby for several reasons. You can verify this by running command which ruby. If it says /usr/bin/ruby,” it signifies the system Ruby, which is undesired. If you encounter errors while installing a gem or running bundle install, ensure you’re using the correct Ruby version.

This is why we recommend that all Ruby projects have .ruby-version file that Chruby can recognise. This prompts chruby to automatically detect and switch to the defined version when entering the project directory.

Steps to automatically switch to the correct version

The most recommended way to automatically switch between the versions or to the correct version is to add a .ruby-version file with the desired version number (such as 3.1.4) in a Ruby project. Once done, test it to see if it works.

1. Create a folder and cd into it.

2. Create a file named .ruby-version containing the version number 3.1.4 with the below command.

Ensure that you have 3.1.4 already installed. If not, either install it or substitute 3.1.4 with a version that is already installed. You can verify installed versions by executing chruby.

3. cd to a directory external to your project, such as your home folder, using the command: cd ~

4. Execute ruby -v. The output will likely display 2.6.10 (or an earlier version), which corresponds to the Ruby version pre installed on macOS.

5. Return to your project directory by using cd -. The hyphen serves as a shortcut to revert to the previous directory in the terminal.

6. Confirm that ruby -v displays 3.1.4.

7. Then delete the test folder using this code:

If your project has a Gemfile, it’s recommended to define the Ruby version within the Gemfile. You can simplify the process and ensure consistency with the version specified in the .ruby-version file. You can do it just by including the following line in your Gemfile just before the initial gem declaration:

The first few lines of Gemfile might look like this:

What if you’re using projects with older Ruby versions?

If you’re trying to engage with an existing Ruby project equipped with a Gemfile and/or a .ruby-version file specifying a version predating 3.2.3, 3.1.4, 3.0.6, or 2.7.8, you may need to either update your application to utilise a more recent version (the preferred approach) or installing the outdated version stipulated in your project (not advisable).

It’s necessary to understand the concept when working with Ruby, as many individuals expend valuable time attempting to install outdated Ruby versions when the optimal solution lies in updating the project instead.

For instance, installing Ruby 2.7.0 or 2.7.1 on an Apple Silicon Mac (without using Rosetta, which is not recommended) is impractical. Instead, upgrading your project to at least version 2.7.8 is recommended, with subsequent migration to 3.1.4, given that Ruby 2.7 reached its end of life in March 2023.

Challenges with existing projects

Despite establishing a proper Ruby development environment, it’s essential to recognise that this may not automatically resolve issues specific to your project. For instance, encountering errors post-executing bundle install in an older Ruby project, or when attempting to run a Jekyll site using bundle exec jekyll serve, or a Rails application with bin/rails s, may stem from outdated gems and/or Ruby versions within your project.

How to address issues in existing projects?

For this, we recommend you ensure that all your gems are up to date, as outdated gems often serve as the primary source of errors.

For instance, ffi frequently causes errors on Apple Silicon Macs (M1/M2). If you encounter ffi in any error message, it likely indicates usage of a version preceding 1.15.2.

In this case, try updating ffi to the latest version using the command:

Repeat this process with any other gems mentioned in the error messages.

Upgrade the Ruby version in your project:

We strongly advise upgrading your projects to at least Ruby 2.7.8, followed by version 3.1.4, as Ruby 2.7.8 reached its end of life in March 2023.

Important note regarding gems across different Ruby versions:

Each Ruby version maintains separate installations of gems. For instance, if you’ve installed Jekyll and/or Rails in version 3.1.4, subsequently installing Ruby 2.7.8 will necessitate reinstalling them in the new Ruby version.

When installing gems in any Ruby version, always employ the command gem install followed by the gem’s name. Avoid using sudo for gem installations.

Next steps:

You now have the essential knowledge required for gem installations on a Mac. However, you may require additional tools for working with Jekyll or Rails, such as Postgres, Node, Redis, and Yarn. Ruby on Mac simplifies this process by installing and configuring all necessary components, enabling you to commence work promptly.