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.
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:
- 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.
- 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.
- 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.)
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.
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.
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:
- click the Windows start-menu button,
- type 'Command Prompt' (or just 'cmd'),
- right-click the 'Command Prompt' app icon that appears, and
- select 'Run as Administrator'.
- Windows may ask if you want to let the Command Prompt make changes to your computer: click 'Yes'.
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.)
- Follow the installation steps at chocolatey.org/install carefully.
- 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.
- 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.
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 18.104.22.168 and 22.214.171.124. 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.
- To install, run
choco install ruby --version 2.3.3 -y.
- Check that Ruby 2.3.3 is installed by running
- You can also go and see in File Explorer that Chocolatey has put Ruby 2.3.3. in a folder probably at
- To install, run
Again, close the Command Prompt and open it again as an administrator.
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:
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
Next, you're going to read through and then carefully follow the installation steps at github.com/oneclick/rubyinstaller/wiki/Development-Kit.
Skim the whole page before you start, so that you find the detailed steps and know what's coming. (A good tip for any walk-through.)
You'll be asked to extract the DevKit files to a permanent location. To do this, I recommend you create a
RubyDevKitfolder on your
C:\RubyDevKit. Save and extract the DevKit zip file there.
When you get to the steps where you run the
ruby dk.rbcommands, do this at the Command Prompt in
C:\RubyDevKit. That is, your command prompt will show
C:\RubyDevKit>where you're about to type.
When that guide asks you to 'edit the generated
config.ymlfile to include installed Rubies', you'll want to add
- C:\tools\ruby23at 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\ruby23as mentioned earlier.
Again, close the Command Prompt and open it again as an administrator.
Install Jekyll. If the DevKit is set up, then installing Jekyll is easy, just run
gem install jekyll. (You can run this command from any folder, since it installs Jekyll globally.)
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. (You can run this command from any folder, since it installs Bundler globally.)
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 126.96.36.199 -y
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\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.