How to Install a Jekyll Theme (Step-by-Step Guide for 2026)

Installing a Jekyll theme is one of the first things you will do when building a static site. Whether you are using GitHub Pages, a local Jekyll setup, or deploying to Netlify, this guide walks you through every method clearly and completely.

Prerequisites

Before installing a theme, make sure you have Jekyll installed on your machine:

gem install jekyll bundler
jekyll -v

If you need a full setup guide, see the official Jekyll installation docs.

Method 1: Install a Gem-Based Jekyll Theme

Most modern Jekyll themes are distributed as Ruby gems. This is the recommended approach for new projects.

Step 1: Create a new Jekyll site

jekyll new my-site
cd my-site

Step 2: Add the theme gem to your Gemfile

Open Gemfile and replace or add the theme gem. For example, to install Minimal Mistakes:

gem "minimal-mistakes-jekyll"

Step 3: Update `_config.yml`

theme: minimal-mistakes-jekyll

Step 4: Install dependencies

bundle install

Step 5: Preview your site

bundle exec jekyll serve

Visit http://localhost:4000 to see your new theme in action.

Method 2: Install a Jekyll Theme from GitHub

Many popular themes — including Chirpy, Hydejack, and al-folio — are not gem-based. You install them by forking or cloning the repository.

Option A: Fork the repository (recommended for GitHub Pages)

Go to the theme’s GitHub repository
Click Fork in the top-right corner
Rename the fork to yourusername.github.io
Edit _config.yml to update your site details

Your site will be live at https://yourusername.github.io within minutes.

Option B: Clone and copy files

git clone https://github.com/cotes2020/jekyll-theme-chirpy.git
cd jekyll-theme-chirpy
bundle install
bundle exec jekyll serve

Method 3: Install a Jekyll Theme on GitHub Pages

GitHub Pages supports a limited set of officially supported themes natively. To use one:

Step 1: Open `_config.yml`

remote_theme: pages-themes/minimal@v0.2.0
plugins:
  - jekyll-remote-theme

Step 2: Add the plugin to your Gemfile

gem "jekyll-remote-theme"

Step 3: Push to GitHub

git add .
git commit -m "Add Jekyll theme"
git push

GitHub Pages will build your site automatically.

Note: GitHub Pages only supports a specific list of plugins. If your theme requires unsupported plugins, deploy via Netlify or Cloudflare Pages instead.

Method 4: Install a Remote Theme on GitHub Pages

The jekyll-remote-theme plugin lets you use any public GitHub repository as a theme:

remote_theme: mmistakes/minimal-mistakes
plugins:
  - jekyll-remote-theme

This is the most flexible approach for GitHub Pages users.

Common Installation Errors and Fixes

`Bundler could not find compatible versions`

Run bundle update to resolve dependency conflicts.

`Invalid theme folder`

Make sure the theme name in _config.yml exactly matches the gem name in Gemfile.

`No such file or directory — jekyll`

Jekyll is not installed. Run gem install jekyll bundler first.

Theme shows default Minima styles

Clear the Jekyll cache and rebuild:

bundle exec jekyll clean
bundle exec jekyll serve

Which Installation Method Should You Use?

Method	Best For
Gem-based	Local development, full control
Fork from GitHub	GitHub Pages, theme-specific setup
`remote_theme`	GitHub Pages with any public theme
Clone manually	Customising the theme source

Next Steps

Once your theme is installed, you will want to:

Update _config.yml with your site name, URL, and author details
Add your first post to _posts/
Customise colours and fonts in the theme’s SCSS files

Browse our full collection of Jekyll themes to find the perfect starting point for your project.

References

install jekyll theme jekyll setup github pages tutorial