How to set-up a Ruby and Elixir dev environment on macOS

Updated Jan 2025.

This is the latest version of my dev env set-up guide, perfect for use after getting a new machine or carrying out a fresh install of macOS. You can use this guide for similar web development set-ups too, since the version manager we’ll be using (asdf) is perfect for a large number of different languages.

If you don’t need Ruby or don’t need Elixir, you can just omit those steps. We’ll also add a few other common web development tools or packages. In short, we’ll be covering installation of:

  • Xcode
  • Command line tools
  • Homebrew
  • Git
  • Postgres
  • TextMate
  • MacVim
  • Asdf
  • Ruby
  • Rubygems
  • Rails
  • Erlang
  • Elixir
  • Hex
  • Phoenix

Xcode

Simply download and install Xcode from the App store.

Command Line Tools

Once Xcode has installed, open it, then go to preferences > downloads, and install command line tools. Or alternatively, enter the following in terminal – be sure to start Xcode afterwards so you can agree to their terms:

xcode-select --install

Homebrew

In the terminal copy and paste the following:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow any instructions that are displayed, mine were:

==> Next steps:
- Run these commands in your terminal to add Homebrew to your PATH:
    echo >> /Users/Aston/.zprofile
    echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/Aston/.zprofile
    eval "$(/opt/homebrew/bin/brew shellenv)"

If you want to opt out of analytics:

brew analytics off

Let’s get brewing – installing Postgres, Stats, and Git!

Let’s update Homebrew first:

brew update

Postgres

Then:

brew install postgresql

Then to start Postgres and on startup, run:

brew services start postgresql@14

Then create your initial db:

createdb

Then:

psql
CREATE ROLE postgres LOGIN CREATEDB;

That will create your Postgres user (use CTRL Z to exit).

Installing Stats

Bit of a bonus: this is a nifty stats app, install with:

brew install stats

Installing Git

brew install git

Then in terminal:

git config --global user.name "Your Name"
git config --global user.email "youremail@yourdomain.com"

Installing asdf

In terminal, type:

brew install coreutils curl
brew install asdf

Then add the following to your ~/.zshrc file:

. /opt/homebrew/opt/asdf/libexec/asdf.sh

In terminal:

If you need to upgrade asdf, use brew upgrade asdf.

How to remove asdf

If you ever need to remove asdf, you can do so pretty easily:

  • In your .zshrc remove the line that was added on installation:. . /usr/local/opt/asdf/libexec/asdf.sh
  • Run rm -rf ~/.asdf/ ~/.tool-versions to completely remove all the asdf files from your system.
  • In terminal: brew uninstall --force asdf

Installing Ruby

Skip if you don’t need Ruby and Rails…

In terminal:

asdf plugin-add ruby

To see which versions are available:

asdf list-all ruby

Then install the versions you want with the following just do the following for whichever versions you require:

asdf install ruby 2.7.2
asdf install ruby 3.1.0
asdf install ruby 3.3.0
asdf install ruby latest

Then set your preferred defaults with:

asdf global ruby 3.3.0

And to use a specific version in any particular directory:

asdf local ruby 2.7.2

To add new Rubies:

asdf plugin-update ruby
asdf list-all ruby

Or simply:

asdf install ruby latest

Rubygems and Rails

Open a fresh terminal window and:

gem update --system

If you would prefer docs weren’t installed, add this to your ‘.gemrc’ file (create one if it doesn’t exist):

gem: --no-document

For Rails:

gem install rails
asdf plugin add nodejs
asdf install nodejs latest
asdf global nodejs 23.6.0 (whichever version you installed)
npm install --global yarn

Open a new terminal window and check your versions by:

ruby -v
rails -v
npm -v
yarn --version

Installing Elixir & Erlang

Skip if you don’t need Elixir and Phoenix

In terminal:

asdf plugin-add erlang
asdf plugin-add elixir
brew install kerl
# Kerl is needed for Erlang

To see which versions are available:

asdf list-all erlang
asdf list-all elixir

Then install the versions you want with the following, just replace version numbers with whichever versions you need:

asdf install erlang 27.2
asdf global erlang 27.2
asdf install elixir 1.18.1-otp-27
asdf global elixir 1.18.1-otp-27

If installation does not work (with something like ERROR: 'asdf_27.2' is not a kerl-managed Erlang/OTP installation then you might want to try the following then reboot your machine and try the above again..

brew install kerl
brew install ncurses-devel

To use a specific version in any particular directory:

asdf local elixir 1.18.1-otp-27

Installing Hex and Phoenix

mix local.hex

To install Phoenix:

mix archive.install hex phx_new

Finally, check your versions by:

elixir -v
mix phx.new --version

Doesn’t that feel good? Now you can install your favourite code editors!

Code Editors & iTerm

Let’s install TextMate and Neovim as our code editors along with iTerm 2 (I find it works better for Vim and Neovim). I’ve also included instructions for MacVim if you want to use that.

iTerm 2

Download iTerm from and then drag it to your applications folder.

Grab yourself a NerdFont

We’ll need a font to display icons properly. You have two options, you can either set iTerm to use one of the patched fonts from nerdfonts or you can use your usual preferred font so long as it has ligatures and then add a symbols only font to display the icons.

To use a patched font download whichever font you like (RobotoMono is pretty nice) and then unzip the folder, highlight all of the font files and then double click so they are added to macOS (do the same for a symbols only font if you intend to use that). Then go to iTerm > Settings > Profiles > Text > Font and then select your font, then if you want to use a different font for symbols only click on Use a different font for non-ASCII text and then select your symbols font. While here you might want to increase your font size too.

You may also want to take a look at the JetBrains Mono font (it’s free and open source).

TextMate 2

I’m still a huge fan of TextMate as it’s still possibly the most beautiful code editor on macOS – it’s my go to for quick edits. You can download from here: https://macromates.com/download

If you like my Elixify theme download it and follow the instructions from here (but you just need to double click on the TextMate 2 theme called Elixify.tmbundle)

Install Elixir Bundle:

mkdir -p ~/Library/Application\ Support/TextMate/Pristine\ Copy/Bundles

cd ~/Library/Application\ Support/TextMate/Pristine\ Copy/Bundles

git clone https://github.com/elixir-editors/elixir-tmbundle.git Elixir.tmbundle

Vim

History: Vi was created in 1976 and was designed to run via the terminal. Vim (aka Vi Improved) was released in 1991. Since then a number of variants have appeared, from SpaceMacs (basically Vim on Emacs), GUI applications like MacVim, and more recently, forks like Neovim (which arrived in 2014). Neovim quickly gained traction and is now one of the most widely used Vims. There are also lots of nice distributions, and two of the most popular are LazyVim and LunarVim. We’ll install LazyVim in a moment. First, here’s how to instal MacVim if you want it or want to take a look at at..

MacVim

MacVim is a GUI application which runs Vim. There’s talk of support for Neovim coming but it’s not quite there yet. Should you install MacVim? If you wan to run a GUI Vim on Mac then it’s a great choice. If you want to run Neovim, then you may want to skip it. If you want to install it, simply:

brew install MacVim

If you want to use Janus with MacVim, it can be installed by running this in terminal:

curl -L https://bit.ly/janus-bootstrap | bash
vim ~/.gvimrc.after

In it paste:

color elixify
set guifont=Monaco:h12
let g:NERDTreeWinPos = "right"
set guioptions-=T " Removes top toolbar
set guioptions-=r " Removes right hand scroll bar
set go-=L " Removes left hand scroll bar
autocmd User Rails let b:surround_{char2nr('-')} = "<% \r %>" " displays <% %> correctly
:set cpoptions+=$ " puts a $ marker for the end of words/lines in cw/c$ commands

Then in terminal, to give it some breathing space at the top do:

defaults write org.vim.MacVim MMTextInsetTop ‘5’

To install the Elixify theme download from here and follow the instructions for MacVim.

mkdir ~/.vim/colors
cd ~/.vim/colors
open .
//copy Elixify.vim there

Neovim

Many (if not most) Vim users now use Neovim. It’s much more like a fully fledged IDE. That and being able to create plugins in Lua is probably its biggest pro, however the con is there’s more to set-up/learn. As I said tho, for modern dev, many if not most devs will probably be using it over Vim. I recommend you give it a go!

brew install neovim

Adding a Neovim distro

There are many Neovim distributions, two of the most popular that I have come across are LazyVim and LunarVim. Let’s install LazyVim:

# Run these if you already have a distro:
mv ~/.config/nvim{,.bak}
mv ~/.local/share/nvim{,.bak}
mv ~/.local/state/nvim{,.bak}
mv ~/.cache/nvim{,.bak}

# Clone the starter
git clone https://github.com/LazyVim/starter ~/.config/nvim

# Remove the .git folder, so you can add it to your own repo later
rm -rf ~/.config/nvim/.git

# Install a command-line fuzzy finder like fzf
brew install fzf

# Start NeoVim! (in iTerm)
nvim


To be continued…