Issues installing Jekyll on macOS Mojave

Some macOS users are reporting install issues so I took some time to try figure it out. The end goal is to solve this and improve the docs.

I was able to successfully install Jekyll with the following steps.

Install Xcode Command Line Tools

  1. Install the Xcode Command Line Tools using your Terminal app.

    xcode-select --install
    
  2. You will get a prompt and have to click the install button.

    (We don’t need Xcode ignore get Xcode option ).

  3. After installing the Xcode Command Line Tools you need to install the macOS SDK headers with the following command in your terminal.

    open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
    

    These SDK headers are already included with an Xcode install tho.


Next we Install Homebrew a package manager for macOS.

Why?

We will use Homebrew to install rbenv.

Why macOS already comes with a version of Ruby?

A lot of the system directories in macOS are locked down making it unusable so we will use rbenv to manage Ruby.


Install Homebrew

  1. Install Homebrew by entering the following command in your Terminal app and hitting the RETURN key.

    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
    
  2. You will now be prompted to hit the RETURN key again to continue.

    Output:

MacBook-Pro:jekyll-test-site Colin$ /usr/bin/ruby -e "$(curl -fsSL       https://raw.githubusercontent.com/Homebrew/install/master/install)"
==> This script will install:
/usr/local/bin/brew
/usr/local/share/doc/homebrew
/usr/local/share/man/man1/brew.1
/usr/local/share/zsh/site-functions/_brew
/usr/local/etc/bash_completion.d/brew
/usr/local/Homebrew
==> The following new directories will be created:
/usr/local/include
/usr/local/sbin
/usr/local/var
/usr/local/opt
/usr/local/share/zsh
/usr/local/share/zsh/site-functions
/usr/local/var/homebrew
/usr/local/var/homebrew/linked
/usr/local/Cellar
/usr/local/Caskroom
/usr/local/Homebrew
/usr/local/Frameworks

Press RETURN to continue or any other key to abort
  1. You will be prompted to enter your Admin Password to allow the install to continue.

Output:

==> /usr/bin/sudo /bin/mkdir -p /usr/local/include /usr/local/sbin /usr/local/var /usr/local/opt /usr/local/share/zsh /usr/local/share/zsh/site-functions /usr/local/var/homebrew /usr/local/var/homebrew/linked /usr/local/Cellar /usr/local/Caskroom /usr/local/Homebrew /usr/local/Frameworks
Password:

The Homebrew install will continue.

Output:

==> /usr/bin/sudo /bin/chmod g+rwx /usr/local/include /usr/local/sbin /usr/local/var /usr/local/opt /usr/local/share/zsh /usr/local/share/zsh/site-functions /usr/local/var/homebrew /usr/local/var/homebrew/linked /usr/local/Cellar /usr/local/Caskroom /usr/local/Homebrew /usr/local/Frameworks
==> /usr/bin/sudo /bin/chmod 755 /usr/local/share/zsh /usr/local/share/zsh/site-functions
==> /usr/bin/sudo /usr/sbin/chown Colin /usr/local/include /usr/local/sbin /usr/local/var /usr/local/opt /usr/local/share/zsh /usr/local/share/zsh/site-functions /usr/local/var/homebrew /usr/local/var/homebrew/linked /usr/local/Cellar /usr/local/Caskroom /usr/local/Homebrew /usr/local/Frameworks
==> /usr/bin/sudo /usr/bin/chgrp admin /usr/local/include /usr/local/sbin /usr/local/var /usr/local/opt /usr/local/share/zsh /usr/local/share/zsh/site-functions /usr/local/var/homebrew /usr/local/var/homebrew/linked /usr/local/Cellar /usr/local/Caskroom /usr/local/Homebrew /usr/local/Frameworks
==> /usr/bin/sudo /bin/mkdir -p /Library/Caches/Homebrew
==> /usr/bin/sudo /bin/chmod g+rwx /Library/Caches/Homebrew
==> /usr/bin/sudo /usr/sbin/chown Colin /Library/Caches/Homebrew
==> Downloading and installing Homebrew...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (28/28), done.
remote: Total 115547 (delta 20), reused 36 (delta 19), pack-reused 115500
Receiving objects: 100% (115547/115547), 26.92 MiB | 350.00 KiB/s, done.
Resolving deltas: 100% (84431/84431), done.
From https://github.com/Homebrew/brew
* [new branch]          master     -> origin/master
* [new tag]             0.1        -> 0.1
* [new tag]             0.2        -> 0.2
* [new tag]             0.3        -> 0.3
* [new tag]             0.4        -> 0.4
* [new tag]             0.5        -> 0.5
* [new tag]             0.6        -> 0.6
* [new tag]             0.7        -> 0.7
* [new tag]             0.7.1      -> 0.7.1
* [new tag]             0.8        -> 0.8
* [new tag]             0.8.1      -> 0.8.1
* [new tag]             0.9        -> 0.9
* [new tag]             0.9.1      -> 0.9.1
* [new tag]             0.9.2      -> 0.9.2
* [new tag]             0.9.3      -> 0.9.3
* [new tag]             0.9.4      -> 0.9.4
* [new tag]             0.9.5      -> 0.9.5
* [new tag]             0.9.8      -> 0.9.8
* [new tag]             0.9.9      -> 0.9.9
* [new tag]             1.0.0      -> 1.0.0
* [new tag]             1.0.1      -> 1.0.1
* [new tag]             1.0.2      -> 1.0.2
* [new tag]             1.0.3      -> 1.0.3
* [new tag]             1.0.4      -> 1.0.4
* [new tag]             1.0.5      -> 1.0.5
* [new tag]             1.0.6      -> 1.0.6
* [new tag]             1.0.7      -> 1.0.7
* [new tag]             1.0.8      -> 1.0.8
* [new tag]             1.0.9      -> 1.0.9
* [new tag]             1.1.0      -> 1.1.0
* [new tag]             1.1.1      -> 1.1.1
* [new tag]             1.1.10     -> 1.1.10
* [new tag]             1.1.11     -> 1.1.11
* [new tag]             1.1.12     -> 1.1.12
* [new tag]             1.1.13     -> 1.1.13
* [new tag]             1.1.2      -> 1.1.2
* [new tag]             1.1.3      -> 1.1.3
* [new tag]             1.1.4      -> 1.1.4
* [new tag]             1.1.5      -> 1.1.5
* [new tag]             1.1.6      -> 1.1.6
* [new tag]             1.1.7      -> 1.1.7
* [new tag]             1.1.8      -> 1.1.8
* [new tag]             1.1.9      -> 1.1.9
* [new tag]             1.2.0      -> 1.2.0
* [new tag]             1.2.1      -> 1.2.1
* [new tag]             1.2.2      -> 1.2.2
* [new tag]             1.2.3      -> 1.2.3
* [new tag]             1.2.4      -> 1.2.4
* [new tag]             1.2.5      -> 1.2.5
* [new tag]             1.2.6      -> 1.2.6
* [new tag]             1.3.0      -> 1.3.0
* [new tag]             1.3.1      -> 1.3.1
* [new tag]             1.3.2      -> 1.3.2
* [new tag]             1.3.3      -> 1.3.3
* [new tag]             1.3.4      -> 1.3.4
* [new tag]             1.3.5      -> 1.3.5
* [new tag]             1.3.6      -> 1.3.6
* [new tag]             1.3.7      -> 1.3.7
* [new tag]             1.3.8      -> 1.3.8
* [new tag]             1.3.9      -> 1.3.9
* [new tag]             1.4.0      -> 1.4.0
* [new tag]             1.4.1      -> 1.4.1
* [new tag]             1.4.2      -> 1.4.2
* [new tag]             1.4.3      -> 1.4.3
* [new tag]             1.5.0      -> 1.5.0
* [new tag]             1.5.1      -> 1.5.1
* [new tag]             1.5.10     -> 1.5.10
* [new tag]             1.5.11     -> 1.5.11
* [new tag]             1.5.12     -> 1.5.12
* [new tag]             1.5.13     -> 1.5.13
* [new tag]             1.5.14     -> 1.5.14
* [new tag]             1.5.2      -> 1.5.2
* [new tag]             1.5.3      -> 1.5.3
* [new tag]             1.5.4      -> 1.5.4
* [new tag]             1.5.5      -> 1.5.5
* [new tag]             1.5.6      -> 1.5.6
* [new tag]             1.5.7      -> 1.5.7
* [new tag]             1.5.8      -> 1.5.8
* [new tag]             1.5.9      -> 1.5.9
* [new tag]             1.6.0      -> 1.6.0
* [new tag]             1.6.1      -> 1.6.1
* [new tag]             1.6.10     -> 1.6.10
* [new tag]             1.6.11     -> 1.6.11
* [new tag]             1.6.12     -> 1.6.12
* [new tag]             1.6.13     -> 1.6.13
* [new tag]             1.6.14     -> 1.6.14
* [new tag]             1.6.15     -> 1.6.15
* [new tag]             1.6.16     -> 1.6.16
* [new tag]             1.6.17     -> 1.6.17
* [new tag]             1.6.2      -> 1.6.2
* [new tag]             1.6.3      -> 1.6.3
* [new tag]             1.6.4      -> 1.6.4
* [new tag]             1.6.5      -> 1.6.5
* [new tag]             1.6.6      -> 1.6.6
* [new tag]             1.6.7      -> 1.6.7
* [new tag]             1.6.8      -> 1.6.8
* [new tag]             1.6.9      -> 1.6.9
* [new tag]             1.7.0      -> 1.7.0
* [new tag]             1.7.1      -> 1.7.1
* [new tag]             1.7.2      -> 1.7.2
* [new tag]             1.7.3      -> 1.7.3
* [new tag]             1.7.4      -> 1.7.4
* [new tag]             1.7.5      -> 1.7.5
* [new tag]             1.7.6      -> 1.7.6
* [new tag]             1.7.7      -> 1.7.7
* [new tag]             1.8.0      -> 1.8.0
* [new tag]             1.8.1      -> 1.8.1
* [new tag]             1.8.2      -> 1.8.2
* [new tag]             1.8.3      -> 1.8.3
* [new tag]             1.8.4      -> 1.8.4
HEAD is now at 38493a35a Merge pull request #5373 from EricFromCanada/man-page-text
==> Homebrew is run entirely by unpaid volunteers. Please consider donating:
https://github.com/Homebrew/brew#donations
==> Tapping homebrew/core
Cloning into '/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core'...
remote: Enumerating objects: 4877, done.
remote: Counting objects: 100% (4877/4877), done.
remote: Compressing objects: 100% (4682/4682), done.
remote: Total 4877 (delta 48), reused 295 (delta 4), pack-reused 0
Receiving objects: 100% (4877/4877), 4.03 MiB | 774.00 KiB/s, done.
Resolving deltas: 100% (48/48), done.
Tapped 2 commands and 4662 formulae (4,919 files, 12.5MB).
==> Migrating /Library/Caches/Homebrew to /Users/Colin/Library/Caches/Homebrew...
==> Deleting /Library/Caches/Homebrew...
Already up-to-date.
==> Installation successful!

==> Homebrew has enabled anonymous aggregate formulae and cask analytics.
Read the analytics documentation (and how to opt-out) here:
https://docs.brew.sh/Analytics

==> Homebrew is run entirely by unpaid volunteers. Please consider donating:
https://github.com/Homebrew/brew#donations
==> Next steps:
- Run `brew help` to get started
- Further documentation:
https://docs.brew.sh

As you can see we have now installed Homebrew successfully.

Install rbenv

  1. Install rbenv with the following command using Homebrew.
brew install rbenv

Output:

MacBook-Pro:jekyll-test-site Colin$ brew install rbenv
Updating Homebrew...
==> Auto-updated Homebrew!
Updated 1 tap (homebrew/core).
==> Updated Formulae
diff-pdf                doctl                   fluent-bit              pdftoedn                pdftoipe                poppler

==> Installing dependencies for rbenv: autoconf, pkg-config and ruby-build
==> Installing rbenv dependency: autoconf
==> Downloading https://homebrew.bintray.com/bottles/autoconf-2.69.mojave.bottle.4.tar.gz
==> Downloading from https://akamai.bintray.com/97/9724736d34773b6e41e2434ffa28fe79feccccf7b7786e54671441ca75115cdb?__gda__=exp=1544304844~hmac=6c
######################################################################## 100.0%
==> Pouring autoconf-2.69.mojave.bottle.4.tar.gz
==> Caveats
Emacs Lisp files have been installed to:
  /usr/local/share/emacs/site-lisp/autoconf
==> Summary
🍺  /usr/local/Cellar/autoconf/2.69: 71 files, 3.0MB
==> Installing rbenv dependency: pkg-config
==> Downloading https://homebrew.bintray.com/bottles/pkg-config-0.29.2.mojave.bottle.tar.gz
==> Downloading from https://akamai.bintray.com/85/85e5bbffb3424f22cd1bf54b69161110481bab100f9abea54e0a0f00fcf761b9?__gda__=exp=1544304849~hmac=c5
######################################################################## 100.0%
==> Pouring pkg-config-0.29.2.mojave.bottle.tar.gz
🍺  /usr/local/Cellar/pkg-config/0.29.2: 11 files, 627.2KB
==> Installing rbenv dependency: ruby-build
==> Downloading https://github.com/rbenv/ruby-build/archive/v20181207.tar.gz
==> Downloading from https://codeload.github.com/rbenv/ruby-build/tar.gz/v20181207
######################################################################## 100.0%
==> ./install.sh
🍺  /usr/local/Cellar/ruby-build/20181207: 427 files, 214.8KB, built in 7 seconds
==> Installing rbenv
==> Downloading https://homebrew.bintray.com/bottles/rbenv-1.1.1.mojave.bottle.1.tar.gz
######################################################################## 100.0%
==> Pouring rbenv-1.1.1.mojave.bottle.1.tar.gz
🍺  /usr/local/Cellar/rbenv/1.1.1: 36 files, 62.8KB
==> Caveats
==> autoconf
Emacs Lisp files have been installed to:
  /usr/local/share/emacs/site-lisp/autoconf
  1. Set up rbenv in your shell.
rbenv init

Output:

MacBook-Pro:jekyll-test-site Colin$ rbenv init
# Load rbenv automatically by appending
# the following to ~/.bash_profile:

eval "$(rbenv init -)"

  1. You can add the above line manually or run the following command to update your .bash_profile file.
echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
  1. Close your Terminal window and open a new one so your changes take effect.

  2. Verify that rbenv is properly set up using this rbenv-doctor script:

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

Output:

MacBook-Pro:jekyll-test-site Colin$ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
Checking for `rbenv' in PATH: /usr/local/bin/rbenv
Checking for rbenv shims in PATH: OK
Checking `rbenv install' support: /usr/local/bin/rbenv-install (ruby-build 20181207)
Counting installed Ruby versions: none
  There aren't any Ruby versions installed under `/Users/Colin/.rbenv/versions'.
  You can install Ruby versions like so: rbenv install 2.2.4
Checking RubyGems settings: OK
Auditing installed plugins: OK
  1. You can now list all available version of Ruby using rbenv install -l.

  2. Let’s install the latest stable release which is currently Ruby 2.5.3 as of writing.

rbenv install 2.5.3

Output:

MacBook-Pro:jekyll-test-site Colin$ rbenv install 2.5.3
ruby-build: use openssl from homebrew
Downloading ruby-2.5.3.tar.bz2...
-> https://cache.ruby-lang.org/pub/ruby/2.5/ruby-2.5.3.tar.bz2
Installing ruby-2.5.3...
ruby-build: use readline from homebrew
Installed ruby-2.5.3 to /Users/Colin/.rbenv/versions/2.5.3
  1. List all Ruby versions known to rbenv
rbenv versions

Output:

MacBook-Pro:jekyll-test-site Colin$ rbenv versions
  system
* 2.5.3 (set by /Users/Colin/.rbenv/version)
  1. Set the global version of Ruby.
rbenv global 2.5.3
  1. Confirm your global version of Ruby is set.
rbenv global

Output:

MacBook-Pro:jekyll-test-site Colin$ rbenv global
2.5.3

Install Bundler

  1. Installing Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.
gem install bundler

Output:

MacBook-Pro:jekyll-test-site Colin$ gem install bundler
Fetching: bundler-1.17.1.gem (100%)
Successfully installed bundler-1.17.1
Parsing documentation for bundler-1.17.1
Installing ri documentation for bundler-1.17.1
Done installing documentation for bundler after 3 seconds
1 gem installed

Installing Jekyll

  1. Install Jekyll
gem install jekyll
  1. Check the Jekyll version.
jekyll -v

Done! :crossed_fingers:

How to update Jekyll

Bundler will update all your gems to the latest versions by simply running bundle update in a Terminal window.

Did you find this tutorial helpful?

1 Like

Hi Colin, do you have any easy method (other than reinstall macOS) to wipe the dev environment as you did? Maybe I have issues because during the content trying to make Jekyll work I messed up something. I guess it’s easier to start from scratch again.

I didn’t reinstall macOS.

  1. I made sure macOS Mojave is up to date. (I have a 2015 MacBook Pro which I upgraded from High Sierra to Mojave.)
  2. I removed Xcode from my computer as I don’t need/use it personally. (Optional step, you might not have it installed)
  3. I fully removed Homebrew. See step 0 above. (This is what I mean by removing dev environment)
1 Like

Okay, thanks. Will try to do the same and see if it’s work that way.

Still unable to install Jekyll - everything else is okay :frowning:

Note: rbenv should not be the default install method on Jekyll docs.

It should work fine on macOS 10.14, given you have compilation headers installed and that you change default PATH for gems to ~/gems.

Most of the errors you encounter are related to those two operations.

Note: What is still missing here is a way to check that headers are present in order to compile extensions like ffi.

Check you system:

$ sw_vers
ProductName:	Mac OS X
ProductVersion:	10.14
BuildVersion:	18A391

$ ruby -v
ruby 2.3.7p456 (2018-03-28 revision 63024) [universal.x86_64-darwin18]

$ which ruby
/usr/bin/ruby
  1. Install command line tools

xcode-select --install

  1. Add this to you shell config file (.bashrc, .zshrc)
export GEM_HOME=$HOME/gems
export PATH=$HOME/gems/bin:$PATH

This is recommended whatever method you choose to install Jekyll to avoid file permissions problems.

Relaunch you terminal for the changes to be taken into account or source the config file.

  1. Install bundler and jekyll
$ gem install bundler jekyll
Successfully installed bundler-1.17.1
Successfully installed jekyll-3.8.5
2 gems installed

$ which bundle
/Users/frank/gems/bin/bundle

If the above method does not work for you or you want to run latest Ruby, you should install ruby with homebrew :

brew install ruby

Then add Ruby path to you shell config file (mine is Zsh):

echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

Relaunch your shell

$ source ~/.zshrc

Check ruby version:

$ ruby -v
ruby 2.5.3p105 (2018-10-18 revision 65156) [x86_64-darwin18]

$ which ruby
/usr/local/opt/ruby/bin/ruby 

We now run latest stable Ruby, cool, Jekyll should be a bit faster.

Then follow the normal procedure:

$ gem install bundler jekyll
Successfully installed bundler-1.17.1
Successfully installed jekyll-3.8.5
2 gems installed

Gems should be installed in your home directory:

$ which bundler
/Users/frank/gems/bin/bundler

If you want to be able to run different Ruby development environments, then go with rbenv as @desiredpersona documented above.

2 Likes

@Frank Yaaay! You are the man! I’m closer than ever - I guess fixing the “file permissions problems” part was the key. Now I successfully installed Jekyll - at least this is what the Terminal said. But when I type jekyll -v I have a "command not found’ error message. What’s

wrong?

You shouldn’t use sudo to install gems, hence defining the GEM_HOME in your home directory.

What groups do you belong to? (type groups to find out;)

What are the file permissions of usr/local/lib/ruby ? (it should be 755 aka drwxr-xr-x , type ls -al /usr/local/lib/ruby to check it out )

@Frank This is what I get when I type the commands:

Thanks for your time @Frank.

It’s the weekend so no rush, but I have a few questions for you.

For me, I don’t have a .bashrc file.

  1. Do users just need to create that .bashrc file themselves if it doesn’t exist. (I don’t use Zsh.)
  2. Is it necessary to reference that .bashrc file within your .bash_profile so that it loads.

you’re welcome @desiredpersona :smile:

I would answer yes to both.
But I guess you should be able to change GEM_PATH in your ~/.bash_profile.

See https://stackoverflow.com/questions/415403/whats-the-difference-between-bashrc-bash-profile-and-environment for more details on the difference between those files.

1 Like

Official documentation has been updated to reflect the tips shared in this post:

1 Like

Thats great! Thanks again @Frank

1 Like

@desiredpersona, @Frank, I have followed all the instruction suggested by you except the fact that I have not uninstalled homebrew. I am still getting issued while building native extensions during “gem install jekyll”. It is doing all the gem installation under $HOME/gems so there should not be any permission issues, but it is still failing.

Compilation problems are related to the installation of command line tools.

I had to install manually SDK headers when I upgraded, but some users have then reported that this package was not present on their system:

This is the last missing piece of the puzzle, we need to figure out.

I think what I did was download commandline tools and install manually from: https://developer.apple.com/download/more/

That installed the SDK package installer for me in

-rw-r--r--  1 root  admin  15944693 25 Oct 08:04 /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg

I could then use that installer to install SDK headers
I did this after I upgraded to mojave.
I reinstalled xcode (downloaded from the above link), and then install commandline tools (downloaded from the above link), and THEN installed SDK headers

2 Likes

Ran into the same issue when upgrading, was able to resolve this based off this StackOverflow answer.

RANLIB=/usr/bin/ranlib bundle update

This is on macOS 10.14.2, with xcode-select version 2354, Ruby 2.5.3p105, Bundler 1.17.3.

I just tried the method in in the original post above (which was the setup I already had, but hadn’t tried deleting Homebrew), but I still have the FFI issue (as described in the GitHub issue linked in the post).

I also tried running open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg (which prompted an install dialogue). Still same result when trying to install Jekyll.

What am I missing? What is the key to resolving this issue?

new error today (on my mac):

Traceback (most recent call last):
1: from /Users/pwillard/gems/bin/bundle:23:in <main> /Users/pwillard/gems/bin/bundle:23:inload’: cannot load such file – /usr/local/lib/ruby/gems/2.6.0/gems/bundler-1.17.2/exe/bundle (LoadError)

I had a freshly installed Mac OS Mojave. Not an upgrade. Didn’t install much on it yet.

I had the issue where it couldn’t find the headers. Followed the guide here. Did not help.
Using rbenv but it did not help so I uninstalled it again.
I downloaded Xcode from Apple and ran /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg

It installs correctly now.

1 Like