Instantly share code, notes, and snippets.

Embed
What would you like to do?
Installing Jekyll on Windows

Installing Jekyll on Windows

Getting Jekyll installed on Windows can be more complicated than on, say, OSX and Ubuntu, but not by much. This outlines the steps I use.

I have similar guidance (plus extra steps for my publishing tools) for OSX written up here.

Why is this tricky?

Because each of the pieces that make Jekyll work is fussy, especially on Windows, which the developers of those pieces rarely use.

Most Ruby applications, including Jekyll, comprise original code as well as a bunch of open-source gems built by others. Several of the gems that Jekyll depends on need Ruby to behave in very particular ways. So we need a setup that caters for all of them.

To complicate matters, there are several versions of Ruby, and not all gems work on all versions. Moreover, some gems need code that isn't available in a standard Ruby installation on Windows; they need a special Ruby development kit installed, too.

And finally, Ruby, Jekyll and its dependencies are developing all the time, so in future you may need to experiment with upgrading and downgrading the version of Ruby you're using. You really need a Ruby version manager to make this easier. If you don't use a Ruby version manager, it's very easy to end up confused, with various versions of Ruby on your machine all installed in different ways.

Other options

If you Google 'install jekyll on windows' you'll find a range of approaches. They may well be better than mine.

The official Jekyll guide lists the three main approaches:

  1. Using Ubuntu Bash on Windows. New versions of Windows let you use a Linux subsystem to run Linux software without a virtual machine. This means you can install Linux versions of Ruby and Jekyll, which may be simpler to manage. You then use Jekyll from this special Bash command line.
  2. Using RubyInstaller. RubyInstaller.org provides versions of Ruby that you can install directly on Windows. This used to be the only sensible way to install Ruby in Windows.
  3. Using Chocolatey. Chocolatey is a package manager for Windows that you can use to install versions of Ruby easily.

(The excellent, classic guide to installing Jekyll on Windows by Julian Thilo is unfortunately now outdated.)

There are good guides on installing Jekyll with Ubuntu Bash on Windows from Dave Rupert, Richard Banks, and David Burela. There are useful further tips on this approach from @lucasg.

I don't use that approach because I've found using Ubuntu Bash on Windows to be frustrating: it is still early, largely undocumented software with lots of gotchas. More importantly for me, though, the publishing tools that I maintain need to work out of the box with the Windows Command Prompt.

My approach is built on Jekyll's official docs and Burela's old approach: using Chocolatey plus the RubyInstaller guide to installing DevKit.

My experience installing Jekyll on Windows is fairly limited: I've got Jekyll running on two or three Windows machines over a few years, and the steps below worked for me recently (after trial and error with other approaches) on Windows 10 Professional on a new machine. Your mileage may vary.

Steps

If all goes well, this process should take about 20 minutes. Get a cup of tea and take your time. Don't rush anything. If you get stuck, take time to understand what's going wrong before proceeding or trying another approach. And keep notes on what you're doing, so that if you need to undo what you've done, you're able to retrace your steps.

  1. Unless advised otherwise by installation guides I link to, run these steps in the Windows Command Prompt run as Administrator. To open this admin-level prompt:

    1. click the Windows start-menu button,
    2. type 'Commpand Prompt',
    3. right-click the 'Command Prompt' app icon that appears, and
    4. select 'Run as Administrator'.
    5. Windows may ask if you want to let the Command Prompt make changes to your computer: click 'Yes'.
  2. Install Chocolatey. Chocolatey makes it easier to add or remove versions of Ruby on your machine. (There are a few Ruby version managers for Windows, like pik and uru and rvm, but they can go out of date quickly or, like rvm, can be difficult to use.)

    1. Follow the installation steps at chocolatey.org/install carefully.
    2. Check that Chocolatey is installed by running choco --version. If you see the version number, you're all good. Don't proceed if you got errors during the install or don't see the version number.
    3. Close the Command Prompt and open it again as an administrator. Closing and reopening the prompt makes sure that any changes to environment variables made by installation steps are loaded and available in the new prompt.
  3. Install Ruby.

    I used to recommend installing Ruby 2.3.3, because it gave me the fewest problems with installing gems later on. Currently the latest version of Ruby is is 2.5, which not all gems supported at first, and I had gem-installation errors with 2.4 and 2.5. However, I've since been able to install Jekyll and its gems without problems using Chocolatey's Ruby 2.4.1.1 and 2.5.1.2. So while the following steps show how to install Ruby 2.3.3, you can try substituting another Ruby version if you like. See Upgrading Ruby below for more detail on upgrading.

    1. To install, run choco install ruby --version 2.3.3 -y.
    2. Check that Ruby 2.3.3 is installed by running ruby --version.
    3. You can also go and see in File Explorer that Chocolatey has put Ruby 2.3.3. in a folder probably at C:\tools\ruby23.
  4. Again, close the Command Prompt and open it again as an administrator.

  5. Install the Ruby DevKit for Windows. Since we're using Ruby 2.3, we need the Windows DevKit on your machine in order for some native gems to install, such as http_parser.rb. (Ruby 2.4 and later use an alternative to DevKit called MSYS2.) We'll also need to tell Ruby where the DevKit is. To do this:

    1. Go to rubyinstaller.org/downloads. You don't need to download Ruby there, because you've installed Ruby using Chocolatey already. You do need to download the development kit labelled 'For use with Ruby 2.0 to 2.3'. Unless your machine is several years old, you're probably on a 64-bit system and should download DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe.
    2. Next, you're going to read through and carefully follow the installation steps at github.com/oneclick/rubyinstaller/wiki/Development-Kit.
    3. When that guide asks you to 'edit the generated config.yml file to include installed Rubies', you'll want to add C:\tools\ruby23 at the bottom of that file, if it's not already there. This is assuming Chocolatey did, indeed, install Ruby 2.3.3 at C:\tools\ruby23 as mentioned earlier.
  6. Again, close the Command Prompt and open it again as an administrator.

  7. Install Bundler. Bundler makes sure that, when you run Jekyll, you're running it with the correct gems. Installing Bundler is easy, just run gem install bundler.

  8. Install Jekyll. Installing Jekyll is easy, just run gem install jekyll.

Upgrading Ruby

In this guide I recommend using Ruby 2.3.3 because I had trouble installing some gems on later versions on Windows. However, new versions of Ruby do have important features, and the issues I had originally may have been resolved by now.

For instance, Ruby 2.4 will properly downcase non-ASCII characters, which is important. For example, a heading like # Équilibre should get a lowercase ID, like <h1 id="équilibre">Équilibre</h1>, but Ruby 2.3 will give you <h1 id="Équilibre">Équilibre</h1>, which will break or render invalid links to #équilibre in case-sensitive systems (e.g. EpubCheck). This can also be a real pain when you're working with team members using Ruby 2.4 or later.

If you want to try upgrading Ruby you can run:

choco upgrade ruby

or to install a specific version of Ruby, for example:

choco install ruby --version 2.4.1.1 -y`

The list of available versions is here.

If you upgrade, Chocolatey will add the new Ruby version to your PATH, but it will not remove the old version. This is bad: do not leave old versions of Ruby in your PATH, or at least make sure you reinstall your gems in your new Ruby version!

If you upgrade to, say, Ruby 2.4.1, the gems you've been using will still be installed in Ruby 2.3.3 in C:\tools\Ruby23\bin. If you don't reinstall the gems (i.e. run bundle install in a project with a Gemfile), so that they exist in C:\tools\Ruby24\bin, and C:\tools\Ruby23\bin is still in your PATH, your computer will find the old, Ruby 2.3 gems and use them. The gems in C:\tools\Ruby23\bin will use Ruby 2.3. You will think you're using Ruby 2.4, but your gems will be using Ruby 2.3. You will be very confused, and you will lose several hours of your life to this mystery as I have.

The safe option is to edit your PATH to remove C:\tools\Ruby23\bin. That way, when you run Jekyll, you'll get an error telling you gems are missing, and that'll remind you to install them again.

@denismcdonald

This comment has been minimized.

Show comment
Hide comment
@denismcdonald

denismcdonald Jul 11, 2018

Thanks for this, Arthur. I found it helpful.

denismcdonald commented Jul 11, 2018

Thanks for this, Arthur. I found it helpful.

@lalegamero

This comment has been minimized.

Show comment
Hide comment
@lalegamero

lalegamero Jul 23, 2018

Great guide, Arthur. Thank you so much!

lalegamero commented Jul 23, 2018

Great guide, Arthur. Thank you so much!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment