Setting up a local copy of the Wagtail git repository is slightly more involved than running a release package of Wagtail, as it requires Node.js and NPM for building Javascript and CSS assets. (This is not required when running a release version, as the compiled assets are included in the release package.)

If you’re happy to develop on a virtual machine, the vagrant-wagtail-develop setup script is the fastest way to get up and running. This will provide you with a running instance of the Wagtail Bakery demo site, with the Wagtail and bakerydemo codebases available as shared folders for editing on your host machine.

(Build scripts for other platforms would be very much welcomed - if you create one, please let us know via the Wagtail Developers group!)

If you’d prefer to set up all the components manually, read on. These instructions assume that you’re familiar with using pip and virtualenv to manage Python packages.

Install Node.js, version 8. Instructions for installing Node.js can be found on the Node.js download page.
You can also use Node version manager (nvm) since Wagtail supplies a .nvmrc file in the root of the project with the minimum required Node version - see nvm’s installation instructions.

With your preferred virtualenv activated, install the Wagtail package in development mode with the included testing and documentation dependencies:

$ pip install -e '.[testing,docs]' -U

Install Node through nvm (optional):

$ nvm install

Install the tool chain for building static assets:

$ npm install

Compile the assets:

$ npm run build

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. 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. In this case, you should install the site before running the pipinstall-e step, or re-run that step after the site is installed.

Wagtail is meant to be used on a wide variety of devices and browsers. Supported browser / device versions include:

Browser

Device/OS

Version(s)

Mobile Safari

iOS Phone

Last 2

Mobile Safari

iOS Tablet

Last 2

Chrome

Android

Last 2

IE

Desktop

11

Chrome

Desktop

Last 2

MS Edge

Desktop

Last 2

Firefox

Desktop

Latest

Firefox ESR

Desktop

Latest

Safari

macOS

Last 2

We aim for Wagtail to work in those environments. Our development standards ensure that the site is usable on other browsers and will work on future browsers. To test on IE, install virtual machines made available by Microsoft.

IE 11 is gradually falling out of use, and specific features are unsupported in this browser:

All static assets such as JavaScript, CSS, images, and fonts for the Wagtail admin are compiled from their respective sources by gulp. The compiled assets are not committed to the repository, and are compiled before packaging each new release. Compiled assets should not be submitted as part of a pull request.

To compile the assets, run:

$ npm run build

This must be done after every change to the source files. To watch the source files for changes and then automatically recompile the assets, run:

The compiled documentation will now be in docs/_build/html.
Open this directory in a web browser to see it.
Python comes with a module that makes it very easy to preview static files in a web browser.
To start this simple server, run the following commands:

Sphinx caches the built documentation to speed up subsequent compilations.
Unfortunately, this cache also hides any warnings thrown by unmodified documentation source files.
To clear the built HTML and start fresh, so you can see all warnings thrown when building the documentation, run:

$cd docs/
$ make clean
$ make html

Wagtail also provides a way for documentation to be compiled automatically on each change.
To do this, you can run the following command to see the changes automatically at localhost:4000: