Updating WagtailCMS

May 22, 2023

Step-by-Step Guide: Updating Your WagtailCMS Website on a RHEL Server for Improved Functionality and Security.


Wagtail is a popular content management system that allows users to create and manage websites easily. However, as with any software, it's important to keep it up-to-date to ensure security and performance. In this blog post, we'll discuss the steps involved in manually updating Wagtail hosted on a Red Hat based Linux server. We'll cover everything from preparing for the update to troubleshooting common issues that may arise. By the end of this post, you'll be equipped with the knowledge you need to update your Wagtail site with confidence.


Before updating Wagtail, it's important to prepare for the update process.

Upgrade Steps

  1. SSH into your Linux host with a user that has sudo privilages.
  2. If you have a separate user that manages your Wagtail environment, switch into that user using this command, in my case I have a user named "wagtail".
    1. $ sudo su - <user>
    2. NOTE: I like to use tmux with two terminals, one for the wagtail user and one for a user with sudo privileges. This helps with not having to constantly switch between users.
  3. Change into the root directory of your project. This will be the directory that has the manage.py file.
  4. Edit your requirements.txt file to reference the version you'd like to upgrade to.
    1. Example: wagtail>=5.0,<5.1
  5. After saving the file, upgrade Wagtail using the pip command.
    1. $ pip install -r requirements.txt
  6. Once the upgrade process is complete, run the following commands to migrate any changes to the database.
    1. $ python manage.py makemigrations
    2. $ python manage.py migrate
  7. Fix any errors or warnings that pop up. If you fix errors, run the migration commands again.
  8. Run the collectstatic command to add all the new resources to your static folder.
    1. $ python manage.py collectstatic --no-input
  9. Restart your web server (Gunicorn, uWSGI, etc...) and test your website to make sure everything works as expected.


If you encounter any issues during the Wagtail update process, try these troubleshooting steps:

  1. Check the release notes to make sure you followed all the necessary steps, and that any prerequisites are in place. Make sure you're updating to a version that's compatible with your current setup.
  2. If you're using third-party packages or plugins make sure they're compatible with the new version. Check the documentation or contact the package/plugin developer for guidance.
  3. Seek support: If you can't resolve the issue on your own, reach out to the Wagtail community or the support team for assistance. Provide as much detail as possible about the issue, including any error messages or log files.
  4. As a last resort you can always redeploy your site using the most recent backup to get back to a functional state while you look further into why the upgrade failed.

By following these troubleshooting steps, you should be able to resolve any issues that may arise during the update process. Remember to always backup your data before making any updates or changes to your site.


Updating Wagtail can seem like a daunting task, but it's an essential step to keep your site running smoothly and securely. By following the steps outlined in this blog post, you can successfully update Wagtail on both your development and production servers. Remember to always create a backup of your data before making any changes or updates, and to review the release notes and troubleshooting steps carefully to avoid any compatibility issues. If you encounter any issues, don't hesitate to seek support from the Wagtail community or the support team. With these tips, you can keep your Wagtail site up-to-date and running smoothly.

Additional Resources

Return to blog index