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

Verifying a successful theme installation

After installation, confirm the theme is applying correctly before making any content changes. A theme that appears to install but shows the default Minima styles has usually encountered one of three problems: the gem name in _config.yml does not exactly match the gem name in Gemfile, the Gemfile.lock has not been updated, or there is a cached build from a previous state.

Run the following sequence to verify:

bundle exec jekyll clean    # Clear the cache
bundle exec jekyll serve    # Fresh build

Open your browser at http://localhost:4000 and compare the result to the theme’s official live demo. The structure and visual design should match. If your site still shows the old design, double-check that theme: in _config.yml matches the gem name exactly — including hyphens and underscores.

For remote themes (remote_theme:), also verify that jekyll-remote-theme is listed in both plugins: in _config.yml and in your Gemfile. Both are required — the plugin declaration in config and the gem in Gemfile must be present simultaneously.

Understanding the theme file override system

Installing a theme is only the starting point. Jekyll’s override system is how you customise it without modifying the theme’s source files. This is important because modifying files inside the gem’s directory means your changes are overwritten when the theme updates.

Jekyll resolves files using a priority order: your project directory first, then the theme gem, then Jekyll’s defaults. This means any file you create at the same path as a theme file takes precedence.

For example, to customise the header in Minimal Mistakes, you copy the theme’s _includes/masthead.html to your project’s _includes/masthead.html and edit your local copy. Jekyll uses your version; the theme’s version is ignored.

To find a theme gem’s files:

bundle info minimal-mistakes-jekyll
# Outputs: /path/to/gems/minimal-mistakes-jekyll-4.x.x

# Browse the theme's files
ls /path/to/gems/minimal-mistakes-jekyll-4.x.x/

Common files to override: _layouts/default.html for global structure, _includes/head.html for custom meta tags and scripts, _sass/ files for colour and typography changes, and assets/css/main.scss for the CSS entry point.

Managing multiple theme options locally

When evaluating multiple themes before committing, the cleanest approach is to create separate Git branches for each theme you are testing:

git checkout -b test-minimal-mistakes
# Install Minimal Mistakes, run bundle install, test
git checkout -b test-chirpy
# Install Chirpy, run bundle install, test

This keeps each theme test isolated — you can switch between them with git checkout and run each locally to compare. When you decide which to use, merge that branch into main and delete the others.

Alternatively, create separate directories for each test if you prefer not to use branches:

jekyll new test-minimal-mistakes
cd test-minimal-mistakes
# Install theme, test

The side-by-side comparison approach is especially valuable when you are evaluating themes for a client project or a blog that will be a long-term investment, because visual and performance differences that are not obvious from demo screenshots become clear when you run the theme with real content.

Keeping your theme updated

Gem-based themes release updates that add features, fix bugs, and maintain compatibility with newer Jekyll and Ruby versions. Staying reasonably current with updates protects your site from compatibility issues.

Check for updates with:

bundle outdated

This lists all gems with newer versions available. To update a specific theme:

bundle update minimal-mistakes-jekyll

Before updating, read the theme’s changelog on its GitHub releases page. Major version bumps (3.x → 4.x) sometimes introduce breaking changes — configuration key renames, layout changes, or dropped features — that require updating your _config.yml or front matter. Minor version bumps (4.2 → 4.3) are typically safe to apply without review.

After updating, run bundle exec jekyll clean && bundle exec jekyll serve and review your site locally before pushing to production. Check your homepage, a post page, category pages, and any heavily customised pages where your overrides might interact with theme changes.

Understanding gem theme licensing

Most Jekyll themes are released under the MIT License, which allows commercial and personal use, modification, and redistribution with attribution. However, not all themes use permissive licenses, and some premium themes use proprietary licenses that restrict redistribution or require payment for commercial use.

Before using any theme professionally, read the license file in the theme’s repository. Key questions: Can you use it on a client project? Can you use it commercially? Are you required to keep the attribution? Can you modify and redistribute it?

MIT, ISC, and Apache 2.0 licenses are permissive and suitable for most uses. GPL licenses require that any derivative work also be open source — which may be a consideration if you are building a private business site. Proprietary licenses from premium themes may restrict the number of sites you can deploy the theme to.

JekyllHub’s theme directory includes license information for each theme, making it straightforward to find a theme that fits both your design and legal requirements. Browse Jekyll themes by category and filter by license to find options that work for your specific project.

What to do right after installing

Once the theme is running locally and matching its demo, complete these steps before publishing:

Update _config.yml with your site details. At minimum: title, description, url (your domain), baseurl, and author information. Many themes also have theme-specific config keys that control navigation, social links, and feature toggles — read the theme’s documentation for the full list.

Customise the homepage content. Delete or replace the theme’s placeholder text and images. A site live on the internet with placeholder content from the theme demo reflects poorly and confuses search engines.

Write at least one real post. A theme looks completely different with your own content versus the demo content. Writing your first real post early in the process helps you identify any layout or typography issues specific to your content style.

Test on multiple screen sizes. Open Chrome DevTools, toggle the responsive design view, and test at 375px (mobile), 768px (tablet), and 1280px (desktop). Themes that look great at desktop width sometimes have layout problems at mobile widths — better to discover and fix these before launch.

Check the live demo against your local build. If there are significant visual differences between the theme’s official demo and your local installation, the cause is usually missing content or configuration. Work through the theme’s configuration guide to ensure you have set up all required fields.

Set up your deployment pipeline. Whether you are using GitHub Pages, Netlify, or another host, configure the deployment before you need it. A working deployment pipeline from day one means every commit can go live — no scrambling to set up hosting when you are ready to publish your first real post.

Your theme is installed — now make it yours

Once the theme passes all your checks, you are ready to start customising. Work through the theme’s documentation to understand which files are safe to edit versus which are owned by the theme gem, then begin with colour variables and typography before touching layout or structure. A well-installed Jekyll theme is a solid foundation — everything after this point is about making it feel like your own site.

install jekyll theme jekyll setup github pages tutorial