Jekyll on Windows
While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks.
Installing Ruby and Jekyll
Installation via RubyInstaller
The easiest way to install Ruby and Jekyll is by using the RubyInstaller for Windows.
RubyInstaller is a self-contained Windows-based installer that includes the Ruby language, an execution environment, important documentation, and more.
We only cover RubyInstaller-2.4 and newer here. Older versions need to install the Devkit manually.
- Download and install a Ruby+Devkit version from RubyInstaller Downloads. Use default options for installation.
- Run the
ridk installstep on the last stage of the installation wizard. This is needed for installing gems with native extensions. You can find additional information regarding this in the RubyInstaller Documentation
- Open a new command prompt window from the start menu, so that changes to the
PATHenvironment variable becomes effective. Install Jekyll and Bundler using
gem install jekyll bundler
- Check if Jekyll has been installed properly:
You may receive an error when checking if Jekyll has been installed properly. Reboot your system and run
jekyll -v again.
If the error persists, please open a RubyInstaller issue.
That’s it, you’re ready to use Jekyll!
Installation via Bash on Windows 10
If you are using Windows 10 version 1607 or later, another option to run Jekyll is by installing the Windows Subsystem for Linux.
You must have Windows Subsystem for Linux enabled.
Make sure all your packages and repositories are up to date. Open a new Command Prompt or Powershell window and type
Your terminal should now be a Bash instance. Next, update your repository lists and packages:
sudo apt-get update -y && sudo apt-get upgrade -y
Next, install Ruby. To do this, let’s use a repository from BrightBox, which hosts optimized versions of Ruby for Ubuntu.
sudo apt-add-repository ppa:brightbox/ruby-ng sudo apt-get update sudo apt-get install ruby2.5 ruby2.5-dev build-essential dh-autoreconf
Next, update your Ruby gems:
gem install jekyll bundler
Check your Jekyll version:
That’s it! You’re ready to start using Jekyll.
You can make sure time management is working properly by inspecting your
_posts folder. You should see a markdown file
with the current date in the filename.
Non-superuser account issues
If the `jekyll new` command prints the error "Your user account isn't allowed to install to the system RubyGems", see the "Running Jekyll as Non-Superuser" instructions in Troubleshooting.
Bash on Ubuntu on Windows is still under development, so you may run into issues.
If you use UTF-8 encoding, make sure that no
BOM header characters exist in your files. If they don’t, Jekyll will break. This is especially relevant when 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. Run the following:
Time Zone Management
Since Windows doesn’t have a native source of zoneinfo data, the Ruby Interpreter doesn’t understand IANA Timezones.
Using them had the
TZ environment variable default to UTC/GMT 00:00.
Though Windows users could alternatively define their blog’s timezone by setting the key to use the POSIX format of defining timezones, it wasn’t as user-friendly when it came to having the clock altered to changing DST-rules.
Jekyll now uses a rubygem to internally configure Timezone based on established IANA Timezone Database.
While ‘new’ blogs created with Jekyll v3.4 and greater, will have the following added to their
Gemfile by default, existing
sites will have to update their
Gemfile (and installed gems) to enable development on Windows:
# Windows does not include zoneinfo files, so bundle the tzinfo-data gem gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
TZInfo 2.0 incompatibility
Version 2.0 of the TZInfo library has introduced a change in how timezone offsets are calculated. This will result in incorrect date and time for your posts when the site is built with Jekyll 3.x on Windows.
We therefore recommend that you lock the Timezone library to version 1.2 and above by listing
gem 'tzinfo', '~> 1.2' in your
Jekyll uses the
listen gem to watch for changes when the
--watch switch is specified during a build or serve.
listen has built-in support for UNIX systems, it may require an extra gem for compatibility with Windows.
Add the following to the
Gemfile for your site if you have issues with auto-regeneration on Windows alone:
gem 'wdm', '~> 0.1.1', :install_if => Gem.win_platform?
You have to use a Ruby+Devkit version of the RubyInstaller and install
the MSYS2 build tools to successfully install the