Julius Nick

Using Jekyll on Windows Subsystem for Linux (WSL2)

January 2021 -- Linux, Websites, Jekyll

Being both a linux and windows user, I recently started using the windows subsystem for linux more frequently. The Windows Subsystem for Linux, or in short WSL, is a compatibility layer for running Linux binary executables natively on Windows. It’s easy to install on a system running windows 10 (it is built-in and just needs to be activated), and I found it straight forward to use, especially when developing with VS Code. Besides running Jekyll in WSL, I also do some Python development using the remote WSL integration of VS Code. I am yet to try working with docker containers in this context, which is next up on my list - but now let’s focus on getting Jekyll to work in this setup.

I am running Ubuntu version 20.04.1 LTS on WSL. One thing I noticed is that it is important to move the directory containing the source code to the WSL filesystem. I placed it in a folder sitting in my home directory. Before I did that, I had the files in the windows filesystem. The build process was much slower that way, especially when using the --livereload option. If you are building a larger site, you might want to consider the --incremental option which could further speed up the build process. For this site, I don’t use incremental regeneration as the build completes so quickly in this setup that I do not care about further speeding it up.

My first contact with Jekyll was trying to get it to run on a mac. I ran into some troubles but succeeded eventually, so I was hoping to have a better experience doing this on my windows machine running WSL. It has to be noted that I am not a native Mac user, as I mostly use Linux and Windows systems, so don’t be discouraged by my somewhat biased mac experience.


This was my first experience working with Ruby, and not having worked with Ruby and gems before, it took me a bit of research to understand how to get Jekyll up and running initially. The official documentation is fairly straight forward, but some details are skipped. What caused me some issues in the beginning was the fact that the full Ruby package seemed to be required to fulfill some of the dependencies. I also had to do some digging, as further missing dependencies popped up in error messages during the following steps of the installation.

Installing dependencies

In any case, here is what worked for me in the end. If you run into any errors, go back and run the dependency installs again.

sudo apt-install ruby-full
sudo apt-get install make gcc gpp build-essential
sudo apt-get install zlib1g zlib1g-dev
sudo apt-get install ruby-dev dh-autoreconf

Install bundler and jekyll

sudo gem update
sudo gem install bundler
sudo gem install jekyll

In the Jekyll repository

Run this once in your website directory after all the other installs have completed successfully.

bundle install

Serving your website locally

Now run the serve command in the top directory of your webpage, and check whether it is served correctly. You can view the page at localhost:4000 in your webbrowser. I use the --livereload option to allow me to view any changes almost instantly, as it causes the browser to auto-refresh:

bundle exec jekyll serve --livereload

My website does not take long to build, the process completes very quickly:

When you are happy with what you have built, you can finally use the bundle exec jekyll build command to generate the complete site, which is by default saved in the _site folder within your repository.

Advice if using a remote repository such as Github

I do a lot of my development work on a powerful desktop machine, but occasionally like to be mobile as well. In order to be flexible, I use git for version control and manage my project with a remote repository. If you do the same, there are some files or folders that do not need to be versioned. You should ignore these files from versioning to avoid cluttering your repo with cache files and other data that is not required when building or developing on other machines. As I use git, I added these folders to the gitignore file to keep them out of version control. This is the content of my .gitignore file:


Off-topic, but highly recommended…Getting rid of the unnerving tab-complete ‘bell’ in WSL!

By the way, in case you get annoyed by the bell sound every time you hit tab completion or backspace as much as I did, you can append this code to your .inputrc (located in your home folder) to disable the sound:

# disable bell on tab-completion
set bell-style none

I hope you enjoyed this article, that’s it for now - thanks for stopping by!

back to top...