Update (Oct 24, 2017): A new simpler way to install Jekyll using MacPorts is available. So, the following article (written in Feb 2017) is outdated and may not work now!

Jekyll is one of the oldest static site generators and is the most famous SSG (short for Static Site Generator) of all. It considers itself as “blog-aware”. Every other SSG software now includes a way to bring blog functionality in its core, though. It is based on Ruby. MacOS Sierra already has it at version 2.0.0p648. So, installing Jekyll should be straight-forward. But, it isn’t. The tutorials around the internet may usually contain how to install it using brew. There’s nothing wrong with it. But, when there is a way to install it without brew or any other third-party tool, we will have a clean system. So, let’s dive in.

Local install

There are two ways to install most common packages that are requirements for Jekyll. Installing them locally or installing them globally for all users. Since, I use MacOS alone (how many of you share your laptop with others?), I don’t want to install anything globally. Also, installing locally, I can distinguish between the gems installed by MacOS and gems installed by me.

Let’s have a ~/gem directory to hold everything related to RubyGems. Also, let’s have all the executables in ~/gem/bin and update the $PATH environment value. So, if you prefer another path such as ~/.gem, feel free to change it accordingly…

For the default bash shell:

$ mkdir -p ~/gem/bin
$ echo 'export GEM_HOME=~/gem' >> ~/.bash_profile
$ source ~/.bash_profile
$ echo 'gem: --user-install -n~/gem/bin --no-document' >> ~/.gemrc

For fish shell:

$ mkdir -p ~/gem/bin
$ echo 'set GEM_HOME ~/gem' >> ~/.config/fish/config.fish
$ source ~/.config/fish/config.fish
$ echo 'gem: --user-install -n~/gem/bin --no-document' >> ~/.gemrc

A little explanation:

~/.bash_profile(~/.config/fish/config.fish in case of Fish shell) is the file that is used by the default bash shell in macOS to store and load the configuration settings for the terminal/s.

~/.gemrc is the file parsed by gem for custom configurations. This is where we can instruct gem to use ~/gem/bin to keep the executables.

Now let’s try to install bundle that is a dependancy for Jekyll.

$ gem install bundle

If things go smoothly without an error, we can proceed to install Jekyll…

$ gem install jekyll

Usually, this will go through too. If it didn’t, please let me know the actual error in the comments, I will try to help you. Now, time to install a new site locally…


$ jekyll new my-awesome-site
Running bundle install in /Users/yourname/gem/my-awesome-site... 


Your user account isn't allowed to install to the system RubyGems.
  You can cancel this installation and run:

      bundle install --path vendor/bundle

  to install the gems into ./vendor/bundle/, or you can enter your password
  and install the bundled gems to RubyGems using sudo.

  Password:

Possibly, the first road-block in our installation. But, easy to fix as mentioned in the output. Let’s cancel the installation by pressing ctrl+c in the keyboard. This will throw a bunch of errors. Safe to ignore them.


$ cd my-awesome-site
$ bundle install --path vendor/bundle

The last command may take sometime to execute depending on the CPU and network speed. Hold on. It’s worth the wait!

Let’s try to serve the just-installed site…

$ bundle exec jekyll serve
Configuration file: /Users/yourname/gem/my-awesome-site/_config.yml
Configuration file: /Users/yourname/gem/my-awesome-site/_config.yml
            Source: /Users/yourname/gem/my-awesome-site
       Destination: /Users/yourname/gem/my-awesome-site/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
             ERROR: YOUR SITE COULD NOT BE BUILT:
                    ------------------------------------
                    Invalid date '<%= Time.now.strftime('%Y-%m-%d %H:%M:%S %z') %>': Document 'vendor/bundle/ruby/2.0.0/gems/jekyll-3.4.0/lib/site_template/_posts/0000-00-00-welcome-to-jekyll.markdown.erb' does not have a valid date in the YAML front matter.

A quick search revealed two reasons and how to fix both…

$ echo 'exclude:
- vendor/bundle' >> _config.yml
$ bundle exec jekyll serve
Configuration file: /Users/yourname/gem/my-awesome-site/_config.yml
Configuration file: /Users/yourname/gem/my-awesome-site/_config.yml
            Source: /Users/yourname/gem/my-awesome-site
       Destination: /Users/yourname/gem/my-awesome-site/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.611 seconds.
 Auto-regeneration: enabled for '/Users/yourname/gem/my-awesome-site'
Configuration file: /Users/yourname/gem/my-awesome-site/_config.yml
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

Visit http://127.0.0.1:4000/ and viola! You’ll see the new Jekyll site in the browser.

Update (2017-10-07): Included a way to configure the default bash shell for the local installation!