Create Wagtail Project

Michael Yin

Full Stack Developer

Last updated on Mar 07 2021

Table of Contents


By the end of this chapter, you should be able to:

  1. Create a Wagtail project with wagtail start and understand how it works
  2. Have good understanding of the Wagtail project structure

Create Wagtail Project

$ mkdir wagtail_project && cd wagtail_project
$ python3 -m venv env
$ source env/bin/activate

You can also use other tools such as Poetry or Pipenv

Let's install Wagtail

(env)$ pip install wagtail

Next, let's use wagtail command to create a project for us.

(env)$ wagtail start wagtail_bootstrap_blog .

Now, let's get the project running on local env.

# create db tables
(env)$ python migrate
(env)$ python runserver

Now you can visit and you will see a welcome page of Wagtail

Please press CTRL-C to terminate the server.

Next, let's keep learning this great project.


  1. If you want to know how wagtail start work, you can take a look at the source code you will see it run django startproject command with the custom project template
  2. The project template is on Github: Wagtail

Project structure

You have file structure like this

├── Dockerfile
├── db.sqlite3
├── env
├── home
├── requirements.txt
├── search
└── wagtail_bootstrap_blog


  1. Dockerfile is for docker deployment.
  2. db.sqlite3 is a local db file, here we did not specify Wagtail to use other db so default sqlite is used by default.
  3. home and search are Django apps created by Wagtail.

Let's check files in wagtail_bootstrap_blog directory

├── settings
│   ├──
│   ├──
│   ├──
│   └──
├── static
│   ├── css
│   │   └── wagtail_bootstrap_blog.css
│   └── js
│       └── wagtail_bootstrap_blog.js
├── templates
│   ├── 404.html
│   ├── 500.html
│   └── base.html


  1. settings/ is the base settings, settings/ is for development and settings/ is for production.
  2. static contains all static assets used by our Wagtail project.
  3. templates contains all Django templates.


Let's take a look at home/migrations/

def create_homepage(apps, schema_editor):
    # Get models
    ContentType = apps.get_model('contenttypes.ContentType')
    Page = apps.get_model('wagtailcore.Page')
    Site = apps.get_model('wagtailcore.Site')
    HomePage = apps.get_model('home.HomePage')

    # Delete the default homepage
    # If migration is run multiple times, it may have already been deleted

    # Create content type for homepage model
    homepage_content_type, __ = ContentType.objects.get_or_create(
        model='homepage', app_label='home')

    # Create a new homepage
    homepage = HomePage.objects.create(

    # Create a site with the new homepage set as the root
        hostname='localhost', root_page=homepage, is_default_site=True)


  1. When we run python migrate, the create_homepage is executed, which create default home_page and set it as root_page of the localhost site. That is the page we just saw on localhost:8000

Please check home/templates/home/home_page.html, which is the template of the home page

{% extends "base.html" %}
{% load static %}

{% block body_class %}template-homepage{% endblock %}

{% block extra_css %}

{% comment %}
Delete the line below if you're just getting started and want to remove the welcome screen!
{% endcomment %}
<link rel="stylesheet" href="{% static 'css/welcome_page.css' %}">
{% endblock extra_css %}

{% block content %}

{% comment %}
Delete the line below if you're just getting started and want to remove the welcome screen!
{% endcomment %}
{% include 'home/welcome_page.html' %}

{% endblock content %}


  1. {% include 'home/welcome_page.html' %} is the key point here, it make home page display some user friendly welcome message instead of some boring text which has no style.


Integrating Wagtail into a Django project


The source code is available Github/wagtail-bootstrap-blog

Wagtail Tutorial Series:

  1. Create Wagtail Project (this article!)
  2. Create Page Model
  3. Category And Tag Support
  4. Routable Page
  5. You can find more on Wagtail Tutorial Series

Michael Yin

Michael is a Full Stack Developer from China who loves writing code, tutorials about Django, Wagtail CMS and React.

He has published some ebooks on leanpub and tech course on

He is also the founder of the AccordBox which provides the web development services.

Table of Contents

This book will teach you how to build a SPA (single-page application) with React and Wagtail CMS

Read More


Get notified about new great Web Development Tutorial