RVM supports most UNIX like systems and Windows (with Cygwin or Bash on Ubuntu on Windows). The basic requirements are bash, curl, gpg2 and overall GNU version of tools - but RVM tries to autodetect it and install anything that is needed.
Homebrew complements macOS (or your Linux system). Install your RubyGems with gem and their dependencies with brew. “To install, drag this icon” no more. Homebrew Cask installs macOS apps, fonts and plugins and other non-open source software. Development, Homebrew, MacOSX, Ruby 2.0.0, RVM Moving between jobs and setting up new machine can be quite painful at times, I recently moved into new assignment and faced the challenge so to avoid pain for other just summarising the steps I followed for smooth Installation. Install rvm with brew. GitHub Gist: instantly share code, notes, and snippets.
∞Install GPG keys
As a first step install GPG keys used to verify installation package:
In case you encounter an issues check security
∞Basic install
∞Ubuntu
RVM have dedicated Ubuntu package, so please follow instructions posted here: https://github.com/rvm/ubuntu_rvm
If you need a different (newer) version of RVM, after installing base version of RVM check the Upgrading section.
∞Any other system
Install RVM (development version):
Install RVM stable with ruby:
Additionally with rails (poor man's railsinstaller):
Or with jruby, rails and puma:
To install without rubygems-bundler and rvm gems (and also remove those gems from both global.gems and default.gems):
To install with hirb gem (and also add it to global.gems):
To install with rails and haml gems (and also add them to default.gems):
Without autolibs:
For a progress bar when downloading RVM / Rubies:
Point to be noted is, there is a backslash before curl. This prevents misbehaving if you have aliased it with configuration in your ~/.curlrc file.
If you're an existing RVM user and you don't want RVM to attempt to setup your shell to load RVM, you can opt out of this at install time by exporting rvm_ignore_dotfiles=yes, or opt out permanently by setting this in your rvmrc.
∞You can also:
- read the installation documentation below.
- watch the most accurate (but not official) rvm screencast.
- read the most accurate (but not official) rvm cheat sheet.
- starting with Rails? watch the RailsCasts.com on Getting Started with Rails.
∞Installation explained
There are three different ways to install and configure RVM.
- Single-User installations (recommended) - For an isolated install within a user's $HOME, not for root.
- Multi-User installations - For server administrators - For an installation usable by all users on the system - Please note that Single-User supersedes Multi-User. This also used to be called the System-Wide Install. Using this type of installation without knowledge how umask works is a big security risk.
- Mixed mode installations - For an installation usable by all users on the system - with isolated rubies/gemsets within a user's $HOME. Installation instructions are exactly the same as for Multi-User installations, the difference is in users environment.
get.rvm.io is a redirect to https://raw.githubusercontent.com/rvm/rvm/master/binscripts/rvm-installer You could also use full path for the installer:
∞Installation
I recommend you read the installation script yourself. This will give you a chance to understand what it is doing before installing, and allow you to feel more comfortable running it if you do so.
∞1. Download and run the RVM installation script
Installing the stable release version:
To get the latest development state:
Instruct RVM to not change the shell initializations files 'rc' / 'profile':
Please note that from this point it is user responsibility to add sourcing rvm to appropriate files.
For a Multi-User install you would execute the following:
Note: The Multi-User install instructions must be prefixed with the sudo command. However, once the install is complete, and the instructions to add users to the rvm group is followed, the use of either sudo or rvmsudo is no longer required. The sudo command is only to temporarily elevate privileges so the installer can complete its work. If you need to use sudo or rvmsudo after the install is complete, some part of the install directions were not properly followed. This usually is because people execute the install asroot, rather than executing the installation instructions from a non-privileged user account.
Installing a specific version:
Prefix the 'bash' portion with 'sudo', of course, if you wish to apply this to a Multi_user Install. Please feel free to check out our upgrading docs for more details on branch format.
Debugging installation process:
If the rvm install script complains about certificates you need to follow the displayed instructions.
Single-User Install Location: ~/.rvm/
If the install script is run as a standard, non-root user, RVM will install into the current users's home directory.
Modification of user configuration files (*rc / *profile) - RVM by default will modify user startup files, although it is not recommended you can disable automated process and do this manually:
Multi-User Install Location: /usr/local/rvm
If the install script is run prefixed with sudo, RVM will automatically install into /usr/local/rvm. Please see the troubleshooting page for an important note regarding Multi-User Installs.
Please see the FAQ page for an important note regardingroot only installs.
External tutorials
Note that that any outside tutorials are NOT supported whether they work or not. Tutorials are great, however we have spent massive amounts of man hours debugging the installation process. Please use the install process(es) from this site only, as this is the only supported installation types and methods.
To update an existing RVM installation
It is safe to simply re-run the installation script again, or you can follow the upgrading docs.
∞2. Load RVM into your shell sessions as a function
Single-User:
The rvm function will be automatically configured for every user on the system if you install as single user. Read the output of installer to check which files were modified.
Multi-User:
The rvm function will be automatically configured for every user on the system if you install with sudo. This is accomplished by loading /etc/profile.d/rvm.sh on login. Most Linux distributions default to parsing /etc/profile which contains the logic to load all files residing in the /etc/profile.d/ directory. Once you have added the users you want to be able to use RVM to the rvm group, those users MUST log out and back in to gain rvm group membership because group memberships are only evaluated by the operating system at initial login time. Zsh not always sources /etc/profile so you might need to add this in /etc/**/zprofile:
Mixed mode (user gemsets):
- After following above instructions for Multi-User.
- Select a user as a manager - he will be responsible for installing new rubies. This user should never run the command introduced below. If this happens, remove/rename the
${HOME}/.rvmrc, logout and then relogin. Otherwise you won't be able to install/upgrade new rubies correctly. For each user that want to use RVM, an additional command needs to be run (once) for each user:
Gemsets created by these users will be hosted in their HOME directory. It's not possible to use global gemsets from system without using tricks like manually linking directories and they should not be used in mixed-mode. Please bear in mind that 'system' in this context does not refer to your distribution's ruby packages, but to the RVM Multi-User installation.
You have two possibilities to manage RVM. The first one is to add managers to the rvm group. The second one is to use separate managers with rvmsudo and privilege escalation. Note that it is not safe to use rvmsudo from mixed mode user. Both can be mixed without any side-effect. It is however very important to not enable mixed-mode gemsets or rubies for the managers. RVM is using a custom umask (umask u=rwx,g=rwx,o=rx) when installing gemsets, rubies, updating itself, etc. This should not impact your system. But if you prefer to avoid RVM messing around with your umask, you can comment the umask line in /etc/rvmrc.
This mode should also works with passenger, please follow passenger instructions. .
∞3. Reload shell configuration & test
Close out your current shell or terminal session and open a new one (preferred). You may load RVM with the following command:
If installation and configuration were successful, RVM should now load whenever you open a new shell. This can be tested by executing the following command which should output rvm is a function as shown below.
NOTE: Before reporting problems check rvm notes as it might contain important information.
Congratulations! You have successfully installed RVM.
∞Try out your new RVM installation
Below are some examples of how to install and use a Ruby under RVM.
Display a list of all known rubies. NOTE: RVM can install many more Rubies not listed.
Install a version of Ruby (eg 2.1.1):
Use the newly installed Ruby:
Check this worked correctly:
Optionally, you can set a version of Ruby to use as the default for new shells. Note that this overrides the 'system' ruby:
∞Enjoy using RVM!
∞Where to now?
If you are new to RVM I recommend that you read the basics page. At the end of the basics page there are further links for getting started.
∞Troubleshooting Your Install
When you run
and got the notice
ca-certificatesneed to be installed:If you open a new shell and running:
does not show
rvm is a function, RVM isn't being sourced correctly.Ensure that RVM is sourced after any path settings as RVM manipulates the path. If you don't do this, RVM may not work as expected.
If you are using GNOME on Red Hat, CentOS or Fedora, ensure that the Run command as login shell option is checked under the Title and Command tab in Profile Preferences. After changing this setting, you may need to exit your console session and start a new one before the changes take affect.
If you came here looking how to install Xcode using brew (aka Homebrew), read this part first. Otherwise, skip to the introduction.
The solution depends on your answer to this question:
- Are you planning on developing iOS or Mac applications?
If the answer is 'no', then you do not need Xcode. All you need are the standalone Command Line Tools, which you can install by reading this guide.
If the answer is 'yes', then you will need to download and install Xcode from the Apple App Store. Xcode is a Mac application built by Apple, and it cannot be installed with Homebrew.
Even if you answered 'yes', you will still need Homebrew and Ruby to install cocoapods, for example, so you should read this guide.
Introduction
After following many outdated and incomplete instructions for setting up a web development environment on a Mac (back in March 2012), and spending a lot of time finding solutions to the problems I encountered along the way, I decided to put together this detailed tutorial.
Over time, the tools got better, and ever since Mavericks, setting up a development environment on a Mac with Apple's standalone Command Line Tools, Homebrew, Git, a Ruby manager (such as chruby, rbenv, or RVM), Ruby, and Rails has been a fairly stress-free process that's no longer fraught with the issues I ran into in 2012.
In fact, the whole process can now be automated via the script that I wrote for you.
While it's certainly possible to set everything up manually, it's not as straightforward to explain because there are more options to consider in 2021. For example, the installation instructions will differ depending on your shell (Bash, zsh or fish), or if you are using a Mac with the Apple Silicon (M1) chip versus an Intel chip.
My script is smart enough to detect your current setup and install everything in the right place.
If you prefer to do everything manually, keep reading. This tutorial is kept up to date and is guaranteed to work in 2021.
Prerequisites
Supported macOS versions:
- Big Sur
- Catalina
- Mojave
Your macOS software is up to date
Before you start, make sure you have the latest Apple software updates for your current macOS version. Check by going to System Preferences, then Software Update.
Homebrew is ready to brew
You can skip this section if you know you haven't tried to install Homebrew yet. If you're not sure, check the contents of the /usr/local folder (also check /opt/homebrew if you're on a Mac with the Apple Silicon chip). Run this command in the Terminal app:
If there's nothing in the folder, then you don't have Homebrew.
If you've already installed Homebrew, you'll want to make sure that when you run brew doctor, it says Your system is ready to brew.
If it's not ready to brew, one of the most common issues, and the first one you should fix, is missing or outdated Command Line Tools. The outdated tools message looks like this:
Here are other variations of the outdated message:
The missing tools message looks like this:
Homebrew usually provides detailed instructions for fixing things, so read carefully and follow their instructions. Quit and restart Terminal once the CLT are installed.
If you get errors other than the ones above, read through the Troubleshooting Homebrew section at the bottom of this guide.
You don't have RVM or rbenv installed
Back in 2012, I used to use RVM, but once I automated this process, RVM kept breaking my script, so I switched to the much simpler chruby and have been using it happily every since. chruby is not compatible with RVM and rbenv, so you'll need to uninstall them first.
Uninstall RVM
Then delete any lines related to RVM from these files if they exist:
~/.bash_profile~/.zshrc~/.zprofile
Uninstall rbenv
Follow the rbenv uninstallation instructions, then delete any lines related to rbenv from these files if they exist:
~/.bash_profile~/.zshrc~/.zprofile
If you don't know what the ~ means, or how to edit the files above, read my guide about how to open and edit hidden files (or dotfiles) on a Mac.
Installation
Notes on Terminal
Most of the work you'll be doing in this tutorial will be in the 'Terminal' application.The easiest way to open an application in macOS is to search for it via Spotlight.
The default keyboard shortcut for invoking Spotlight is command-Space. Once Spotlight is up, start typing the first few letters of the app you are looking for, and once it appears, select it, and press return to launch it.
If you are on an M1 Mac, make sure Terminal is NOT in Rosetta mode.
You can check by running this command once Terminal opens:
It should say arm64 if you are on an M1 Mac.
Notes on your shell
This tutorials assumes you are using zsh. If you're not sure, read my guide to find out which shell you are using, and replace any references to .zshrc in the steps below with .bash_profile if you are using Bash.
Step 1: Install Homebrew and the Command Line Tools
Homebrew, 'the missing package manager for macOS,' allows you to easily install hundreds of open-source tools. The full installation instructions are available in the Homebrew Documentation, but you should only need to run the command that's listed at the top of the Homebrew site:
Note that the command listed on the Homebrew site could change, so please make sure that what I have listed above is the same. If it isn't, please let me know and I'll update it.
Copy and paste the command into your Terminal window, press return, then read what appears in the Terminal, and pay attention to any instructions that require your input. For example, Homebrew will prompt for your macOS password. Note that Terminal does not provide visual feedback when you type your password. Just type it slowly and press return.
Homebrew also automatically installs the Apple Command Line Tools, and it usually installs them in the background, but in case this changes, pay attention if any windows appear that require your input.
Once the installation is successful, quit and restart Terminal, then check if Homebrew is ready to go:
If you get Your system is ready to brew, you can move on to Step 2. Otherwise, read what Homebrew is saying very carefully. They usually provide great instructions that you should follow. If that doesn't help, go to the Troubleshooting section to learn how to fix errors and warnings you might run into.
On Apple Silicon Macs, Homebrew might tell you to run a few commands after the installation:
Quit and restart Terminal, then check if everything is working so far:
Step 2: Install chruby and the latest Ruby with ruby-install
Install chruby and ruby-install:
Install Ruby 2.7.2:
There is a newer version of Ruby (3.0.1), but it's not fully compatible with some gems such as Jekyll, so I recommend 2.7.2 to get started. You can always install any other available version of Ruby, in addition to 2.7.2. That's the advantage of using a Ruby manager like chruby. You can have multiple versions on your computer at the same time, and you can easily switch between them.
This will take a few minutes, and once it's done, configure your shell to automatically use chruby:
For Intel Macs
For Apple Silicon Macs
Quit and relaunch Terminal, then check that everything is working:
It should say ruby 2.7.2p137.
Step 3: Configure Rubygems
Disable downloading documentation when install gems (for faster installation):
Make sure Rubygems is up to date:
Step 4: Install and configure Bundler
Rvm Breweries
Install Bundler:
Configure Bundler to take advantage of your computer's cores:
Step 5: Install any other gem you want
Congrats! You now have a working Ruby development environment. You should now be able to installs Rails, or Jekyll, or whatever gem you've been trying to install for the past few days!
If you got any value out of my tutorial, join the 1200+ people who are becoming confident coders through my quality guides and exclusive content in my free newsletter.
Step 6: Install Git
Git is the version control system of choice among many web developers. With Homebrew, installing Git is as easy as this:
Since we just installed Homebrew, we could have skipped brew update, but it's a good habit to run it before installing anything with Homebrew because Homebrew is updated regularly.
Quit and relaunch Terminal, then verify the Git installation:
You should get git version 2.31.1 or later.
Next, you'll need to configure Git with your name and email, and other important settings.
Next Steps
Once you start coding away on your computer, you will most likely need to install more tools with Homebrew. Before you do, remember to always run brew update and brew doctor to make sure your system is still ready to brew. To upgrade your existing packages, run brew upgrade. It's important to keep your development environment up to date, and Homebrew is just one of the tools you need to remember to update.
Knowing when and how to automate is a sign of an effective engineer. Most things you do repeatedly will add up to a lot of wasted time if you don't find ways to speed them up.
That's why I recommend taking advantage of my script, which allows you to keep your system up to date by typing a single word in your Terminal. It does that by adding an alias, which is a shortcut for the longer command. If you're not familiar with aliases, read my guide about how aliases can speed up your workflow.
Troubleshooting Homebrew warnings and errors
Consider starting over from scratch
Before you start looking through this list and trying to fix every warning and error, I would suggest a quick and easy solution: uninstall Homebrew and start over from scratch.
Before you do that, take a screenshot or copy and paste in a text file the list of tools you currently have installed:
If you installed a database with Homebrew (such as Postgres), and stored data that you need, back it up first. It is unusual to have important data stored in a local database and nowehere else, but I'll mention it for completeness.
Then uninstall Homebrew:
This will not completely remove all Homebrew folders, so you'll need to finish the job:
This will prompt you for your macOS password, and then it will say:
This is expected because you can't delete the /usr/local folder itself, but you can delete anything inside it. On a brand new Mac, the /usr/local folder already exists, but it is empty.
To verify that Homebrew was completely removed, check the contents of the /usr/local folder:
It should be empty.
Then go back to step 1, and after you complete this tutorial, run brew list again, and install any missing tools. If you don't recognize the missing tools, or if all your coding projects are still working, then you don't need to install them.
Fix brew issues one by one
In many cases, Homebrew will provide helpful instructions for dealing with warnings and errors, and I usually follow those instructions. I've tried to cover the most common sources of warnings and errors.
If you run into an issue I haven't mentioned, try looking it up in the Homebrew GitHub Issues, or search for the error message on DuckDuckGo. If that doesn't help, subscribe to my newsletter and I'll do my best to help you.
After you fix each issue, run brew doctor until you get Your system is ready to brew. Then go to Step 2.
PATH issues
If you get Warning: /usr/bin occurs before /usr/local/bin, run the command below (as recommended by Homebrew), and quit and relaunch Terminal:
Read my guide about PATH to understand why this is important.
Other similar PATH issues you might see:
Missing directory errors
sudo allows you to run commands as a user with higher access rights, which is why it prompts you for your password, and mkdir stands for 'make directory.'
chown stands for 'change owner,' the -R flag applies this to all nested files and directories, and whoami is a variable that represents your macOS username. You should copy and paste the commands above as is.
Permission errors
If you get /usr/local/etc isn't writable or Cannot write to /usr/local/Cellar or if it complains that any directories inside /usr/local aren't writable, fix it with this command:
This makes you the owner of the /usr/local directory, in addition to all nested directories.
Unbrewed files
Here are examples of common warnings about unbrewed files:
If you get a warning about any type of unbrewed file (such as .pc files, or static libraries), you may need to delete them as suggested by Homebrew (unless you put them there on purpose, which is unlikely). You'll have to delete each file it complains about one by one with the rm command. For example, to remove a file called libgd.2.0.0.dylib from /usr/local/lib, you would run this command:
In some cases, it might list a bunch of files that are all in the same directory, as in this example where something went wrong when installing Node:
In this case, you can delete the entire directory that contains the unbrewed files:
Python warnings and config scripts
A related issue is:
These most likely mean you installed Python with a tool other than Homebrew. If you think you might need this version of Python, then just ignore those warnings. Otherwise, run the command below to remove that version of Python, but read this thread first.
In general, you want to install all development tools with Homebrew.
Outdated or misconfigured Xcode
Unless you plan on building iOS or Mac applications, you don't need Xcode. All you need are the standalone Command Line Tools, which are installed when you follow this tutorial. If you already installed Xcode, you can safely delete it (again, assuming you haven't used it and don't plan to use it).
So, if you get any of the errors below, delete Xcode, then run brew doctor.
Outdated Xcode
Misconfigured Xcode
Linking keg-only formula
Homebrew messages are generally very helpful and they let you know exactly what to do. In this case, it is telling you to fix the linking issue by running brew unlink, followed by the tools (or 'brews') that need to be unlinked. Here, there is only one tool that needs to be unlinked. Therefore, you should run this command:
If it listed more than one tool, you would add them to the command separated by a space, like so:
Unlinked kegs
Broken symlinks
Use brew cleanup to fix these types of warnings:
Deprecated taps
In this case, you need to add the specific cask to the brew untap command, such as:
Missing dependencies
The instructions here are straightforward:
Issues with the Git repo
Follow the instructions:
Rvm Brewing Company
Prefix issues on Apple Silicon
This is caused if you installed Homebrew while running your terminal in Rosetta mode, and are now running it in native mode, or if you used arch -x86_64 while in native mode, or other types of mixing the two environments.
Rvm Brewing
Most things you need for Ruby web development are supported in native mode now, so there's no need to use Rosetta anymore. For more details and things to look out for, read my guide on installing a development environment on Apple Silicon.