Hyde Press

Simple • Static • Blog-aware

Jekyll Installation Guide (Book Edition)

by Tom Preston-Werner, Nick Quaranto, Parker Moore, et al



Note: The book edition is still an early release and a work-in-progess.

This is the (official) documentation for the Jekyll static site builder / generator reformatted in a single-page book edition.

See the source repo for how the book gets auto-built with "plain" Jekyll - of course - and hosted on GitHub Pages.

Questions? Comments? Send them to the Jekyll Talk forum post titled Jekyll Docu Reformatted as a Single-Page in Black 'n' White (Book Version) - Why? Why Not?.



Thanks to all Jekyll contributors for making it all possible.

Part 1 - Getting Started

Chapter 1.1 - Installation

Getting Jekyll installed and ready-to-go should only take a few minutes. If it ever becomes a pain, please file an issue (or submit a pull request) describing the issue you encountered and how we might make the process easier


Installing Jekyll is easy and straight-forward, but there are a few requirements you’ll need to make sure your system has before you start.

Running Jekyll on Windows

While Windows is not officially supported, it is possible to get it running on Windows. Special instructions can be found on our Windows-specific docs page.

Install with RubyGems

The best way to install Jekyll is via RubyGems. At the terminal prompt, simply run the following command to install Jekyll:

$ gem install jekyll

All of Jekyll’s gem dependencies are automatically installed by the above command, so you won’t have to worry about them at all. If you have problems installing Jekyll, check out the troubleshooting page or report an issue so the Jekyll community can improve the experience for everyone.

Installing Xcode Command-Line Tools

If you run into issues installing Jekyll's dependencies which make use of native extensions and are using Mac OS X, you will need to install Xcode and the Command-Line Tools it ships with. Download in Preferences → Downloads → Components.


In order to install a pre-release, make sure you have all the requirements installed properly and run:

gem install jekyll --pre

This will install the latest pre-release. If you want a particular pre-release, use the -v switch to indicate the version you’d like to install:

gem install jekyll -v '2.0.0.alpha.1'

If you’d like to install a development version of Jekyll, the process is a bit more involved. This gives you the advantage of having the latest and greatest, but may be unstable.

$ git clone git://github.com/jekyll/jekyll.git
$ cd jekyll
$ script/bootstrap
$ bundle exec rake build
$ ls pkg/*.gem | head -n 1 | xargs gem install -l

Optional Extras

There are a number of (optional) extra features that Jekyll supports that you may want to install, depending on how you plan to use Jekyll. These extras include LaTeX support, and the use of alternative content rendering engines. Check out the extras page for more information.

ProTip™: Enable Syntax Highlighting

If you’re the kind of person who is using Jekyll, then chances are you’ll want to enable syntax highlighting using Pygments or Rouge. You should really check out how to do that before you go any farther.

Now that you’ve got everything installed, let’s get to work!

Chapter 1.2 - Troubleshooting

If you ever run into problems installing or using Jekyll, here are a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please check out our other help resources as well.

Installation Problems

If you encounter errors during gem installation, you may need to install the header files for compiling extension modules for Ruby 2.0.0. This can be done on Ubuntu or Debian by running:

sudo apt-get install ruby2.0.0-dev

On Red Hat, CentOS, and Fedora systems you can do this by running:

sudo yum install ruby-devel

On NearlyFreeSpeech you need to run the following commands before installing Jekyll:

export GEM_HOME=/home/private/gems
export GEM_PATH=/home/private/gems:/usr/local/lib/ruby/gems/1.8/
export PATH=$PATH:/home/private/gems/bin
export RB_USER_INSTALL='true'

To install RubyGems on Gentoo:

sudo emerge -av dev-ruby/rubygems

On Windows, you may need to install RubyInstaller DevKit.

On Mac OS X, you may need to update RubyGems (using sudo only if necessary):

sudo gem update --system

If you still have issues, you can download and install new Command Line Tools (such as gcc) using the command

xcode-select --install

which may allow you to install native gems using this command (again using sudo only if necessary):

sudo gem install jekyll

Note that upgrading Mac OS X does not automatically upgrade Xcode itself (that can be done separately via the App Store), and having an out-of-date Xcode.app can interfere with the command line tools downloaded above. If you run into this issue, upgrade Xcode and install the upgraded Command Line Tools.

Jekyll & Mac OS X 10.11

With the introduction of System Integrity Protection, several directories that were previously writable are now considered system locations and are no longer available. Given these changes, there are a couple of simple ways to get up and running. One option is to change the location where the gem will be installed (again using sudo only if necessary):

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

Alternatively, Homebrew can be installed and used to set up Ruby. This can be done as follows:

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

Once Homebrew is installed, the second step is easy:

brew install ruby

Advanced users (with more complex needs) may find it helpful to choose one of a number of Ruby version managers (RVM, rbenv, chruby, etc.) in which to install Jekyll.

If you elect to use one of the above methods to install Ruby, it might be necessary to modify your $PATH variable using the following command:

export PATH=/usr/local/bin:$PATH

GUI apps can modify the $PATH as follows:

launchctl setenv PATH "/usr/local/bin:$PATH"

Either of these approaches are useful because /usr/local is considered a “safe” location on systems which have SIP enabled, they avoid potential conflicts with the version of Ruby included by Apple, and it keeps Jekyll and its dependencies in a sandboxed environment. This also has the added benefit of not requiring sudo when you want to add or remove a gem.

Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable)

This error can occur during the installation of jekyll-coffeescript when you don’t have a proper JavaScript runtime. To solve this, either install execjs and therubyracer gems, or install nodejs. Check out issue #2327 for more info.

Problems running Jekyll

On Debian or Ubuntu, you may need to add /var/lib/gems/1.8/bin/ to your path in order to have the jekyll executable be available in your Terminal.

Chapter 1.3 - Jekyll on Windows

While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks. This page aims to collect some of the general knowledge and lessons that have been unearthed by Windows users.


Julian Thilo has written up instructions to get Jekyll running on Windows and it seems to work for most. The instructions were written for Ruby 2.0.0, but should work for later versions prior to 2.2.

Alternatively David Burela has written instructions on how to install Jekyll via Chocolately with 3 command prompt entries


If you use UTF-8 encoding, make sure that no BOM header characters exist in your files or very, very bad things will happen to Jekyll. This is especially relevant if you’re running Jekyll on Windows.

Additionally, you might need to change the code page of the console window to UTF-8 in case you get a “Liquid Exception: Incompatible character encoding” error during the site generation process. It can be done with the following command:

$ chcp 65001


As of v1.3.0, Jekyll uses the listen gem to watch for changes when the --watch switch is specified during a build or serve. While listen has built-in support for UNIX systems, it requires an extra gem for compatibility with Windows. Add the following to the Gemfile for your site:

gem 'wdm', '~> 0.1.0' if Gem.win_platform?