New Wagtail Course! 🥳 The Ultimate Wagtail Developers Course

Upgrading From Wagtail 3.0 to Wagtail 4.0

Upgrading from Wagtail 3.0 to Wagtail 4.0


### Embracing Wagtail 4.0: A New Era of Versioning and Features As we move from Wagtail 3 to Wagtail 4.0, it’s important to note the shift in versioning, adopting a time-based semantic versioning system as detailed on []( This change simplifies understanding the scope and impact of updates. ### Key Changes in Wagtail 4.0 Diving into Wagtail 4.0, a range of new features and optimizations are introduced, which are crucial for maintaining the efficiency and functionality of your site. Review the [major release notes for Wagtail 4.0]( to start familiarizing yourself with these changes: - **Preview Methods Decoupled:** The `Page.serve()` and `Page.serve_preview()` methods are now decoupled to enhance live previews, streamlining content creation and testing processes. - **Dropping Safari 13 Support:** Reflecting the advancement in browser technology, support for Safari 13 has been dropped, allowing for better use of modern web features. - **Model Renaming:** The `PageRevision` model has been renamed to `Revision`, simplifying naming conventions within Wagtail’s framework. ### Choosing the Right Version For this upgrade, you’ll want to target Wagtail 4.2.4, the latest at this point. If you prefer sticking to Long-Term Support (LTS) versions for stability, Wagtail 4.1 is an excellent choice. Check out the [upgrade guide]( to confirm compatibility with Django 4.1 and Python versions from 3.7 to 3.10. ### Updating Your Environment Now, let’s update your project dependencies in the `requirements.txt` file to reflect the new versions: ``` wagtail==4.2.4 Django==4.1.13 ``` Running `python runserver` should now be smoother with these updates. If any packages show issues, consider upgrading or temporarily unpinning them to resolve compatibility problems. ### Addressing Deprecations and Transitions Wagtail 4.0 introduces several deprecations that are critical to address as they will be removed by Wagtail 5.0. It’s crucial to review these changes to avoid future breakdowns or functionality loss: - **Transition from BaseSetting to BaseSiteSetting:** The `BaseSetting` model has been renamed to `BaseSiteSetting`. [Learn more about this transition and how to update your settings models]( ### Running Smoothly on Wagtail 4.0 Once you've made these updates, thoroughly test your project to ensure that everything functions as expected. Pay special attention to deprecated features and consider their impact on your project's long-term maintenance and scalability. By staying informed about these updates and preparing for future changes, you can make the most of Wagtail’s robust framework, keeping your site on the cutting edge of content management technology. 👏 Well, upgrading from Wagtail 3.0 to 4.0 was quick and painless!

Kalob Taulien

Wagtail CMS enthusiast; Wagtail core team member; Coding teacher.

Get notified about new Wagtail content.