Create a gist now

Instantly share code, notes, and snippets.

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. 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.


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 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 2.3.3. Ruby 2.3.3 gave me the fewest problems with installing gems later on (currently the latest version of Ruby is is 2.5, which not all gems support yet. I had gem-installation errors with 2.4 and 2.5.)
    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 seein 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 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
    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.

This comment has been minimized.

Show comment
Hide comment

denismcdonald Jul 11, 2018

Thanks for this, Arthur. I found it helpful.

Thanks for this, Arthur. I found it helpful.

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