How to Run a Jekyll Website Locally on Windows
When we work with a Jekyll website, one of the first things we usually want is a way to run it locally.
Working locally makes development much easier. We can edit a post, change a layout, adjust some CSS, save the file, and immediately see the result in our browser. We don’t have to push every small change to a remote repository just to check whether something works.
Getting Jekyll running on Windows can seem a little complicated at first because several pieces are involved: Ruby, RubyGems, Devkit, Bundler, and the dependencies defined by our project.
Once everything is set up, however, the actual workflow is quite simple.
In this guide, we’ll set up a Windows environment for Jekyll, install Ruby+Devkit using RubyInstaller, install the project’s dependencies with Bundler, build the site, and finally run it locally with live reload.
The process is designed to work with an existing Jekyll website regardless of which theme it uses.
What We’ll Need
Before we begin, we’ll need:
- A Windows computer
- An existing Jekyll website or project
- PowerShell or Command Prompt
- A code editor such as Visual Studio Code
- Ruby+Devkit
We don’t need to install a particular Jekyll theme for this process. The important part is that we have a Jekyll project and, preferably, a Gemfile that defines its dependencies.
1. Installing Ruby+Devkit
Jekyll is built with Ruby, so our first step is to install Ruby.
On Windows, RubyInstaller with Devkit is a convenient option. The development tools are important because some Ruby gems may need to compile native components while we’re installing the project’s dependencies.
We’ll download the appropriate Ruby+Devkit version for Windows from the RubyInstaller project.
When choosing the installer, we’ll make sure to select Ruby+Devkit, rather than a plain Ruby installation.
During the installation, we’ll leave the options that add Ruby to the PATH enabled. The exact wording may vary slightly depending on the RubyInstaller version.
Running the MSYS2 setup
At the end of the RubyInstaller installation, we may be prompted to run ridk install.
If the prompt appears, we’ll run it.
We should see options similar to:
1 - MSYS2 base installation
2 - MSYS2 system update
3 - MSYS2 and MINGW development toolchain
We’ll choose:
3
and press Enter.
This step is important because some Ruby and Jekyll dependencies require native compilation.
We’ll let the installation finish before moving on.
Restarting the terminal
If PowerShell or Command Prompt was already open while we installed Ruby, we’ll close it and open a new terminal window.
This gives the new terminal a chance to pick up the updated PATH configuration.
2. Verifying Ruby
Now let’s make sure Ruby was installed correctly.
We’ll open a new PowerShell window and run:
ruby -v
We should get a Ruby version similar to:
ruby 3.x.x (...)
The exact version will depend on the RubyInstaller release we installed.
Next, we’ll check RubyGems:
gem -v
This should also return a version number.
If both commands work, our Ruby installation is ready.
3. Checking Bundler
Next, we’ll check whether Bundler is available:
bundle -v
If Bundler is already installed, we’ll see its version.
If the terminal tells us that bundle is not recognized, we can install Bundler with:
gem install bundler
After the installation finishes, let’s verify it again:
bundle -v
Bundler is important when we’re working with an existing Jekyll project because it allows us to install and use the dependencies defined by that project’s Gemfile.
Instead of relying on whatever gem versions happen to be installed globally, we can let the project define what it needs.
4. We Don’t Need to Install Jekyll Globally
At this point, it might seem natural to install Jekyll globally with:
gem install jekyll
For an existing Jekyll project, however, we may not need to do this.
If our project contains a Gemfile, we can let Bundler manage the Jekyll version and other dependencies required by the project.
This is useful because different Jekyll projects can require different versions of Jekyll and other gems.
Keeping the dependencies associated with the project helps us avoid unnecessary version conflicts.
5. Moving Into Our Jekyll Project
Now let’s move into the directory containing our Jekyll website.
For example:
cd C:\Projects\my-jekyll-site
The actual path will depend on where we keep our project.
We can check the directory contents with:
dir
A typical Jekyll project might look something like this:
my-jekyll-site/
├── _config.yml
├── Gemfile
├── _posts/
├── _layouts/
├── _includes/
├── _sass/
├── assets/
└── ...
Our project may not have exactly the same structure, and that’s perfectly normal.
Different Jekyll themes and projects can organize their files differently.
The important files we’ll commonly encounter include _config.yml and Gemfile.
6. Understanding the Gemfile
The Gemfile is one of the most important files in a Jekyll project.
It defines the Ruby gems that our project depends on.
For example, a simple project might contain:
source "https://rubygems.org"
gem "jekyll"
A real-world project can have considerably more dependencies.
Some themes and plugins may add their own gems, so we shouldn’t replace an existing Gemfile with a simple example just because it looks easier.
Instead, we’ll work with the Gemfile that belongs to our project.
This is particularly important when we’re working with an existing theme or repository, because its dependencies may be different from those of another Jekyll project.
7. Installing the Project Dependencies
Once we’re inside the project directory, we’ll run:
bundle install
Bundler will read our Gemfile and install the dependencies required by the project.
The first installation may take a few minutes.
If everything goes well, we’ll eventually see something similar to:
Bundle complete!
At this point, the project’s Ruby dependencies should be installed.
If bundle install reports an error, it’s better to look at the actual error before changing anything.
Dependency problems can have different causes, including Ruby versions, incompatible gems, missing development tools, or project-specific requirements.
There isn’t one universal fix for every Bundler error.
8. Building the Site
Before starting the local server, let’s make sure Jekyll can build our site successfully.
We’ll run:
bundle exec jekyll build
If the build succeeds, Jekyll will generate the finished website.
The generated files are normally placed in:
_site/
We may see output similar to:
Configuration file: C:/Projects/my-jekyll-site/_config.yml
Source: C:/Projects/my-jekyll-site
Destination: C:/Projects/my-jekyll-site/_site
Generating...
done in ...
The exact output will vary depending on the project and Jekyll version.
A successful build gives us a good indication that our environment and project dependencies are working correctly.
9. Running Jekyll Locally
Now we’re ready to start the local Jekyll server.
We’ll run:
bundle exec jekyll serve
Jekyll should start a local development server and display an address similar to:
Server address: http://127.0.0.1:4000/
We can open the following address in our browser:
http://localhost:4000
Our Jekyll website should now be running locally.
When we’re finished, we can return to the terminal and press:
Ctrl + C
to stop the server.
10. Enabling Live Reload
During development, manually refreshing the browser every time we make a change can become tedious.
Fortunately, Jekyll provides live reload.
Instead of running the standard server command, we’ll use:
bundle exec jekyll serve --livereload
Now we can edit our files, save them, and let Jekyll rebuild the site while the browser refreshes automatically.
This is especially useful when we’re working on:
- Posts
- Pages
- Layouts
- Includes
- CSS
_config.yml- Other Jekyll source files
Once live reload is working, the development cycle becomes much more pleasant:
Edit → Save → Rebuild → Browser refresh
Our Typical Development Workflow
After the initial setup, our daily workflow becomes quite simple.
First, we’ll move into our project directory:
cd C:\Projects\my-jekyll-site
If we’ve changed dependencies or the project has been updated, we’ll run:
bundle install
Then we’ll start Jekyll with live reload:
bundle exec jekyll serve --livereload
Finally, we’ll open:
http://localhost:4000
From there, we can work normally in our editor.
We edit a file, save it, and check the result in the browser.
What About Different Jekyll Themes?
The basic process we’ve followed isn’t specific to one particular theme.
We can use the same general workflow with a popular theme, a custom theme, or a Jekyll site that doesn’t use a theme at all.
The main difference is usually the project’s dependencies and directory structure.
For example, a theme may require additional gems or plugins. Some repositories may also be theme-development repositories rather than complete websites.
That’s why we should always look at the project’s own Gemfile and configuration instead of assuming that every Jekyll project works exactly the same way.
The overall workflow remains:
Ruby
↓
Bundler
↓
Gemfile
↓
bundle install
↓
Jekyll build
↓
Jekyll serve
↓
http://localhost:4000
Troubleshooting
Ruby Is Not Recognized
If this command:
ruby -v
reports that Ruby is not recognized, we’ll first make sure RubyInstaller completed successfully.
We’ll close PowerShell or Command Prompt, open a new terminal, and try again.
If the problem continues, we’ll check whether Ruby was added to the system PATH during installation.
Bundler Is Not Recognized
Let’s first check:
bundle -v
If Bundler isn’t available, we’ll install it:
gem install bundler
Then we’ll check again:
bundle -v
bundle install Fails
When bundle install fails, we shouldn’t immediately start adding gems to the Gemfile.
Instead, we’ll look at the error message.
It may point to a Ruby version problem, an incompatible dependency, missing development tools, or another project-specific issue.
If the project contains a .gemspec file, that file may also be important because some projects use it to define dependencies.
The correct solution depends on the actual project configuration.
Jekyll Build Fails
If the server doesn’t start, let’s try building the site directly:
bundle exec jekyll build
The build output can often tell us exactly where the problem is.
Rather than focusing only on the final error line, we’ll look for the first meaningful error reported by Jekyll or one of its dependencies.
The Site Looks Different Locally
If the local site starts successfully but doesn’t look the same as the online version, we’ll check the project’s configuration.
Some things worth checking include:
_config.yml- Theme configuration
- Plugins
- Assets
- Base URL settings
- Environment-specific configuration
A successful Jekyll server doesn’t necessarily mean that every configuration setting matches the production website.
A Quick Checklist
Before we consider our local setup complete, let’s verify the basic commands.
Ruby:
ruby -v
RubyGems:
gem -v
Bundler:
bundle -v
From the Jekyll project directory:
bundle install
Build the site:
bundle exec jekyll build
Start the development server:
bundle exec jekyll serve --livereload
Then we’ll open:
http://localhost:4000
If the website loads and our changes appear after saving files, we’re ready to start developing.
Final Thoughts
Setting up Jekyll on Windows can feel like a lot the first time.
We’re dealing with Ruby, RubyGems, Devkit, MSYS2, Bundler, the project’s Gemfile, and finally Jekyll itself. There are several moving parts, and a problem with any one of them can prevent the site from running.
Once the initial setup is complete, though, things become much simpler.
We install Ruby+Devkit, let Bundler manage the project’s dependencies, build the site, and run Jekyll with live reload.
From there, our development workflow is straightforward:
Edit → Save → Rebuild → Preview
That local feedback loop is one of the nicest parts of working with Jekyll. We can experiment with posts, layouts, styles, configuration, and other parts of the site without repeatedly deploying changes just to see how they look.
And most importantly, this workflow isn’t tied to a particular Jekyll theme. Once we understand the basic Ruby, Bundler, and Jekyll workflow, we can apply the same approach to almost any Jekyll project.
Leave a comment