Notes to my future self on getting Ruby sorted on a Mac without wanting to throw the laptop out a window. The system Ruby that ships with macOS is not for your projects - use a version manager.

Why chruby and ruby-install

There are a few options here (rbenv, rvm, asdf), but chruby is dead simple. It does one thing: switches your active Ruby version. ruby-install handles actually building and installing Ruby versions. Together they're about 10 lines of config and no magic.

Install both tools via Homebrew

brew install ruby-install chruby

Add chruby to your shell

You need to source chruby's shell script every time a new terminal opens. Add these lines to your ~/.zshrc:

source /opt/homebrew/opt/chruby/share/chruby/chruby.sh
source /opt/homebrew/opt/chruby/share/chruby/auto.sh

The Apple Silicon gotcha

You may see advice online to add chruby to your .zshrc like this:

# DON'T do this on Apple Silicon
source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh

The idea is that $(brew --prefix) evaluates to Homebrew's install path so you don't have to hardcode it. In practice, on Apple Silicon Macs, this can expand to /usr/local/opt/... - the Intel Homebrew path - instead of the correct /opt/homebrew/opt/.... The evaluation happens at write time in some shell contexts, and if anything in your environment is off, you get the wrong path silently.

Just hardcode it. On M-series Macs, Homebrew lives at /opt/homebrew. Use that path directly and move on.

Install a Ruby version

Once chruby is installed, use ruby-install to pull down the version you want:

ruby-install ruby 3.3.4 #current or desired version

This takes a few minutes - it's compiling Ruby from source. Go get a coffee.

Activate it

Reload your shell config, then switch to the new version:

source ~/.zshrc
chruby ruby-3.3.4

Run chruby with no arguments to see all installed versions:

chruby

Verify the active Ruby:

ruby -v

The auto.sh part

That second line in your .zshrc - auto.sh - enables automatic version switching. If a project directory has a .ruby-version file, chruby will switch to that version automatically when you cd into the folder. Useful when you're jumping between projects that need different Ruby versions.

Getting Jekyll running

Don't install Jekyll globally with gem install jekyll. You'll end up with version conflicts across projects. Let Bundler handle it.

In your Jekyll project directory:

bundle install

This reads the Gemfile, installs the right versions of Jekyll and all its dependencies into the project. Then to start the local server:

bundle exec jekyll serve --livereload

The bundle exec prefix makes sure you're running the Jekyll version specified in your Gemfile.lock, not whatever might be floating around globally. The --livereload flag auto-refreshes the browser when you save a file - makes writing posts a lot less tedious.

Your site will be at http://localhost:4000.

Quick reference

# Install a Ruby version
ruby-install ruby 3.3.4

# See installed versions
chruby

# Switch versions
chruby ruby-3.3.4

# Check active version
ruby -v

# Install project gems
bundle install

# Serve Jekyll locally
bundle exec jekyll serve --livereload