Installing Jekyll on an Apple M1 Mac

M1 Macs are cool - but as noted - sometimes software doesn’t work quite right on them. One of the programs I use often is Jekyll - and out of the box it doesn’t work on my device with Apple’s new M1 chip.

In case this is useful for someone I’ll go over what worked for me when installing Jekyll on an Apple M1 (Mac Mini, macOS Big Sur 11.3.1 (20E241))

Install Xcode

The first step for development on your Apple device is installing Xcode.

You can install Xcode in the Apple App Store.

But you’ll also need to install the Xcode command line tools:

$ xcode-select --install

Install Homebrew

We’ll need to install Homebrew before we can install Ruby and rbenv.

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

Install Ruby & Rbenv

Now that we have Homebrew installed we can install Ruby and rbenv:

$ brew install rbenv ruby-build

# Add rbenv to bash so that it loads every time you open a terminal
$ echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.zshrc
$ source ~/.zshrc

Next install Ruby 3.0.0:

$ rbenv install 3.0.0
$ rbenv global 3.0.0
$ ruby -v
$ rbenv rehash

Add the brew ruby and gems path to your shell configuration:

# If you're using Zsh
echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.zshrc

# If you're using Bash
echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.bash_profile

# Unsure which shell you are using? Type
echo $SHELL

Install Jekyll

After installing Ruby, we can now install Jekyll and Bundler.

We’ll be doing a local install, the Jekyll docs recommend not installing Ruby gems globally to avoid file permissions problems and using sudo.

Install the bundler and jekyll gems:

gem install --user-install bundler jekyll

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

# If you're using Zsh
echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.zshrc

# If you're using Bash
echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bash_profile

# Unsure which shell you are using? Type
echo $SHELL

Check that GEM PATHS: points to your home directory:

gem env

With that we have Jekyll installed!

We can now try get up and running with an example.

Let’s follow the Jekyll Quick-start Instructions:

$ gem install bundler jekyll

$ jekyll new my-awesome-site

$ cd my-awesome-site

# Here you will get an error 😞
$ bundle exec jekyll serve

You should be getting an error that looks something like this:

~/YOURUSERNAME/.gem/ruby/3.0.0/gems/jekyll-4.2.0/lib/jekyll/commands/serve/servlet.rb:3:in `require': cannot load such file -- webrick (LoadError)

Fix Jekyll

We should be able to fix this error (or at least I was able to) by simply adding webrick to our project.

We can do so by following the steps below:

# Update bundler for good measure
$ bundle update --bundler

# Add webrick because otherwise Jekyll won't run on Ruby 3.0 #8523
$ bundle add webrick

# Make sure to rebuild everything. This threw some errors, I had to run this a few times before it worked.
$ bundle install --redownload

# And now:
$ bundle exec jekyll serve

If that did not work for you you should try following all of the steps listed here.

But if it did…

Success!

Power Range Success

And with that - you should now be able to build sites with Jekyll on your M1 Apple!

Colin Gallagher