How To Install Jekyll on Mac (M1 or Intel), the Easy Way

Updated

With this updated guide for 2024, you’ll be able to install Jekyll on your Mac in minutes.

Every day, many people get stuck trying to install Jekyll on macOS due to outdated, incomplete, and confusing instructions. Especially on Apple Silicon Macs. Today, you’re about to save a lot of time and frustration.

Here are the two best ways to install Jekyll on a Mac:

Install Jekyll on Mac with a single command that sets everything up for you in minutes

To install Jekyll on a Mac, you first need a proper Ruby development environment. Even though Macs come preinstalled with Ruby, it’s not recommended to use the system Ruby. To learn more, read why you shouldn’t use the system Ruby.

Setting up a proper Ruby development environment on a Mac involves several steps, which many people fumble when trying to follow long tutorials or videos. You might get confused about which shell you’re using, or why you’re getting a jekyll: command not found error even after successfully installing Jekyll.

And on M1 Macs, many people follow outdated advice to use Rosetta or arch -x86_64, which can lead to all kinds of issues, such as incompatible architecture and failed to load command: jekyll errors:

bundler: failed to load command: jekyll
incompatible architecture (have x86_64 need arm64e)

To eliminate any chance of human error, I built Ruby on Mac, a reliable script that automates the whole process with a single command, and with a perfect result every time. It also automatically installs Jekyll and all the other development tools you’ll need.

It doesn’t just have a one-time use. You can run it over and over to keep your dev tools up to date and secure. And the next time you get a new Mac, it will save you a whole day because it can also automatically install all your Mac apps, fonts, macOS preferences, and GitHub repos, in addition to a complete development environment. You get all of these time savings now and in the future for a one-time cost.

If you’re trying to set up Jekyll on a work computer, you should be able to expense the one-time cost of Ruby on Mac.

Read how much people love Ruby on Mac.

Spend an hour or more installing Jekyll on Mac manually

If you haven’t yet tried to install Ruby or other development tools on your Mac, you should be able to get up and running with the basics by following my step-by-step guide for installing Ruby on a Mac.

If you’ve already tried to set things up and you’re running into issues you can’t figure out, you can still try my step-by-step guide, but Ruby on Mac will get you unstuck much faster.

Install Jekyll

Once you have a proper Ruby development environment, you should be able to install the Jekyll gem and create a new Jekyll site.

First, make sure you’re using a newer version of Ruby, and not the system Ruby (the one that came preinstalled on your Mac). If you’re creating a brand new Jekyll site, I recommend 3.2.3.

Run this command to check which version of Ruby is currently active:

which ruby

If it says /usr/bin/ruby, that’s the system Ruby. You’ll want to switch to one of the versions you installed with a version manager. If you’re a Ruby on Mac customer, you should already have 3.2.3 installed, and you can switch to it like this:

chruby 3.2.3

If it says that 3.2.3 is unknown, then install it. If you’re a Ruby on Mac customer, read the Post-Installation Guides to learn how to install additional Ruby versions. If you’re not a Ruby on Mac customer, look up the instructions for the version manager you’re using.

Then install Bundler and Jekyll:

gem install bundler jekyll

Create a new Jekyll site

cd into the folder where you keep all your projects. For example:

cd ~/projects

Once again, switch to the desired Ruby version. Example:

chruby 3.2.3

You can double check that you are indeed using 3.2.3 with this command:

ruby -v

Generate a new Jekyll site, replacing my-jekyll-site with your desired name:

jekyll new my-jekyll-site

Then cd into your new site:

cd my-jekyll-site

Add a .ruby-version file so that chruby will automatically switch to the desired version whenever you cd into this Jekyll folder:

echo '3.2.3' >> .ruby-version

Now you should be able to run the server:

bundle exec jekyll serve

Why bundle exec jekyll serve, and not just jekyll serve? By prepending bundle exec to any commands, we ensure that we’re using the specific version of the gem that is defined in our Ruby project. This is why you can have multiple versions of the same gem installed on your computer, yet still be able to use specific versions within different projects without worrying about conflicts.

Note about older versions of Jekyll with Ruby 3.x

If you’re using Jekyll older than 4.3.0, and Ruby 3.2.3, or any 3.x version, you’ll need to either update Jekyll to at least 4.3.1, or add the webrick gem to your Gemfile before you can run the Jekyll server. The easiest way is by running this command:

bundle add webrick

If you don’t add webrick, you’ll get a cannot load such file error that looks like this when running the Jekyll server:

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

Before version 3.x, Ruby used to come with the webrick gem out of the box, but then they removed it starting with Ruby 3.0. Because Jekyll uses webrick as its server, if the gem is not installed, it won’t be able to start the server.

Alternatively, you can install Ruby 2.7.8, which comes with webrick, and older versions of Jekyll will work out of the box.