Laurence Mercer

Local (Linux) setup for Wagtail core development

22 July 2025

Local Wagtail core development (that is, developing Wagtail itself locally rather than, for example, a Wagtail-based website) requires a degree of custom setup.

Using the Wagtail documentation as a base (particularly the Development page), this post describes my process for setting up a local environment, specifically on a Linux machine with Debian.

Note: at the time of writing, the latest stable release of Wagtail is 7.0.1 and the core development version is 7.1a0.

1.

If necessary, install fnm. This will be used later to handle the installation of Node.

curl -fsSL https://fnm.vercel.app/install | bash

2.

If necessary, install libjpeg and zlib. These are required by Pillow, which Wagtail uses.

sudo apt install libjpeg62-turbo-dev zlib1g-dev

Note: the Pillow documentation mentions libjpeg8-dev. However, attempting to install this returns an error:

Package 'libjpeg8-dev' has no installation candidate... the following packages replace it: libjpeg62-turbo-dev

3.

Fork and clone the Wagtail GitHub repository.

Note:

  • I keep Wagtail projects in a local ~/wagtail directory. However, this is a personal choice and not required.
  • My GitHub username is input and I'm cloning my Wagtail fork via SSH.
cd ~/wagtail
git clone git@github.com:input/wagtail.git

4.

If necessary, install Node (via fnm).

cd ~/wagtail/wagtail
fnm install

5.

Setup venv:

cd ~/wagtail/wagtail
python3 -m venv .venv
source .venv/bin/activate

6.

Install the Wagtail package in development mode with the included testing and documentation dependencies:

python -m pip install -e ."[testing,docs]" --config-settings editable-mode=strict -U

7.

Install the tool chain for building static assets:

npm ci

8.

Compile the assets:

npm run build

At this point, the documentation notes:

Any Wagtail sites you start up in this virtualenv will now run against this development instance of Wagtail. We recommend using the Wagtail Bakery demo site as a basis for developing Wagtail.

9.

So, install the Wagtail Bakery demo, using the already activated virtual environment (~/wagtail/wagtail/.venv):

cd ~/wagtail
git clone https://github.com/wagtail/bakerydemo.git
cd bakerydemo
python -m pip install -r requirements/development.txt
cp ~/wagtail/bakerydemo/bakerydemo/settings/local.py.example ~/wagtail/bakerydemo/bakerydemo/settings/local.py
cp ~/wagtail/bakerydemo/.env.example ~/wagtail/bakerydemo/.env
python manage.py migrate
python manage.py load_initial_data
python manage.py runserver

10.

As mentioned earlier, at the time of writing, the Wagtail core development (~/wagtail/wagtail) install version is 7.1a0. However, the Bakery demo (~/wagtail/bakerydemo) install uses Wagtail version 7.0.1:

# Excerpt from the bakerydemo install in step 9 
Downloading wagtail-7.0.1-py3-none-any.whl (9.1 MB)
...
Attempting uninstall: wagtail
  Found existing installation: wagtail 7.1a0
  Uninstalling wagtail-7.1a0:
    Successfully uninstalled wagtail-7.1a0
...
Successfully installed... wagtail-7.0.1

As the Wagtail documentation notes, this is to be expected:

Keep in mind that the setup steps for a Wagtail site may include installing a release version of Wagtail, which will override the development version you’ve just set up.

If this occurs, the solution is to:

install the local Wagtail development instance in your virtualenv for your Wagtail site

Like so:

python -m pip install -e ~/wagtail/wagtail"[testing, docs]" --config-settings editable-mode=strict -U

11.

Because the Bakery demo has now been switched to use the Wagtail development install version, further database migrations may be required. So:

cd ~/wagtail/bakerydemo
python manage.py migrate

12.

At this point, everything should be ready. Therefore, as the Wagtail documentation notes:

When editing the Wagtail core code (both HTML and JavaScript) you should be able to refresh the site running locally and see the changes.

To test, first:

  • Start the Bakery demo site
  • Log in with the credentials: admin / changeme
  • The dashboard should show that the site is using Wagtail 7.1a0
  • Start npm to handle static file compilation: npm start

Then:

i.

Make a change to the wagtail/admin/templates/wagtailadmin/home.html template file and confirm you can see the changes on the Wagtail dashboard (home) page

ii.

Add a console.log statement to client/src/entrypoints/admin/wagtailadmin.js and confirm you can see the logging in the browser

Return to blog