Jekyll on macOS

Install Command Line Tools

To install the command line tools to compile native extensions, open a terminal and run:

xcode-select --install

Install Ruby

Jekyll requires Ruby v2.5.0 or higher. macOS Catalina 10.15 ships with Ruby 2.6.3. Check your Ruby version using ruby -v.

If you’re running a previous version of macOS, you’ll have to install a newer version of Ruby.

With Homebrew

To run the latest Ruby version you need to install it through Homebrew.

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

# Install Ruby
brew install ruby

Add the brew ruby path to your shell configuration:

# MacOS Catalina (10.15) users and newer
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshenv

# MacOS Mojave (10.14) users and older
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.bash_profile

# Unsure which version of macOS you are using? Try
sw_vers -productVersion 

Relaunch your terminal and check your Ruby setup:

which ruby
# /usr/local/opt/ruby/bin/ruby

ruby -v
ruby 2.7.2p137 (2020-10-01 revision 5445e04352)

You’re now running the current stable version of Ruby!

With rbenv

People often use rbenv to manage multiple Ruby versions. This is very useful when you need to be able to run a given Ruby version on a project.

# Install Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Install rbenv and ruby-build
brew install rbenv

# Set up rbenv integration with your shell
rbenv init

# Check your installation
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash

Restart your terminal to apply your changes. Next, you can install the Ruby version you want. Let’s install the latest stable version:

rbenv install 2.7.2
rbenv global 2.7.2
ruby -v
ruby 2.7.2p137 (2020-10-01 revision 5445e04352)

That’s it! Head over to rbenv command references to learn how to use different versions of Ruby in your projects.

Install Jekyll

After installing Ruby, install Jekyll and Bundler.

Local Install

Install the bundler and jekyll gems:

gem install --user-install bundler jekyll

Get your Ruby version:

ruby -v
ruby 2.7.2p137 (2020-10-01 revision 5445e04352)

Append your path file with the following, replacing the X.X with the first two digits of your Ruby version:

# MacOS Catalina (10.15) users and newer
echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.zshenv

# MacOS Mojave (10.14) users and older
echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bash_profile

# Unsure which version of macOS you are using? Try
sw_vers -productVersion 

Check that GEM PATHS: points to your home directory:

gem env

Every time you update Ruby to a version in which the first two digits change, update your path to match.

Global Install

We recommend not installing Ruby gems globally to avoid file permissions problems and using sudo.

On Mojave (10.14)

Because of SIP Protections in Mojave, run:

sudo gem install bundler
sudo gem install -n /usr/local/bin/ jekyll

Before Mojave (<10.14)

Run:

sudo gem install bundler jekyll

Troubleshooting

See Troubleshooting or ask for help on our forum.