How to Upgrade Open edX from Ulmo to Verawood with Tutor

To upgrade Open edX Ulmo to Verawood with Tutor, back up the Tutor root, clear the known migration blockers on a staging copy, install Tutor v22 with pip install "tutor[full]>=22.0.0,<23.0.0", upgrade your Tutor plugins, then run tutor local launch. Launch sees that the environment was generated by Tutor v21 (Ulmo), runs the release upgrade steps and the database migrations, and starts Verawood. Two things are specific to this upgrade: the Meilisearch search index must be deleted and rebuilt, and a few Verawood data migrations can fail on older instances unless you fix the data first.

This guide is the operator's runbook for that move on a Tutor-based install, written for administrators and developers who run their own platform. It covers what changes, the pre-flight checks, the upgrade commands for local and Kubernetes deployments, the Meilisearch rebuild, verification and rollback. The commands come from the Tutor documentation and source and were not run on a live site for this article; rehearse them on staging first.

Checked against the Tutor source and documentation at v22.0.3 (27 October 2026), Tutor v21.0.9 (the last Ulmo release, August 2026) and the official Open edX Verawood release notes, including the developer and operator notes. Verawood was released on 30 July 2026. Tutor releases often, so read the changelog for the exact v22 version you install.

What changes between Ulmo and Verawood

Tutor follows the Open edX releases with one major version each: v21 is Ulmo and v22 is Verawood. Ulmo is now listed among the unsupported Open edX releases, so staying on it means no further fixes from the community. Here is what the default Tutor configuration changes between the last release of each line:

The upstream release/verawood.2 tag appeared on 29 October 2026, after Tutor v22.0.3, so check whether a later v22 release has moved to it. For context on where Open edX fits among other platforms, see our open-source LMS guide.

On the platform side, the operator release notes flag these as breaking or behaviour-changing:

• Notifications and notification emails are on by default. The opt-in flags were replaced by opt-out flags notifications.disable_notifications and notifications.disable_email_notifications.
• Email digests are scheduled by Celery. The send_email_digest management command is now a no-op, so remove any cron job that calls it.
• The new instructor dashboard is the default. Custom tabs injected through the legacy instructor dashboard filter no longer appear. The instructor.legacy_instructor_dashboard waffle flag is a temporary way back.
• Legacy content libraries are deprecated and must be migrated to the new content libraries during this release.
• Typesense users need Typesense Server v30.0 or later before deploying. The default search setup is unaffected.
• Help links (HELP_TOKENS_BOOKS) now point to the official Open edX docs unless you override them.

Pre-flight checks that prevent a failed migration

Run these on a copy of production first. The release notes list several Verawood migrations that can fail or take a long time on instances with years of data:

Also check before you start:

1. Plugins. List them with tutor plugins list and confirm each has a Verawood-compatible release. Custom plugins and forks need testing on the new release.
2. Custom images and forks. If you build edx-platform from your own branch, rebase it on the Verawood release tag before upgrading.
3. Disk space. The backup copies the whole Tutor root, including the MySQL, MongoDB and Meilisearch data folders.
4. Host Python. Tutor v22 needs Python 3.10 or later on the machine that runs the tutor command.

Step 1: Back up the Tutor root

With Tutor, the configuration, environment and data all live under one folder, so the documented backup is a copy of that folder with the platform stopped:

tutor local stop
sudo rsync -avr "$(tutor config printroot)"/ /tmp/tutor-backup/

Use a destination with enough space, ideally off the server. If you also want portable dumps, the Tutor docs show how to run mysqldump and mongodump inside the containers with tutor local exec. Keep the old data/meilisearch/data.ms folder in the backup: Meilisearch v1.8.4 cannot read a v1.36.0 database, so a rollback needs the original. Our guide to LMS backup and restore covers retention and restore testing.

Step 2: Upgrade Tutor and its plugins

Pin the major version so you do not jump past Verawood by accident:

pip install --upgrade "tutor[full]>=22.0.0,<23.0.0"
tutor --version
tutor plugins update
tutor plugins upgrade all

tutor plugins update refreshes the plugin index, and tutor plugins upgrade all upgrades every installed plugin it can find in the indexes, printing a warning for any it cannot. Plugins you installed from a file or URL must be upgraded by hand. If you use the pre-built Tutor binary instead of pip, download the v22 binary from the Tutor releases page; the binary cannot load custom plugins.

Step 3: Run the upgrade

Standard images. Run launch:

tutor local launch

Launch compares the major version that generated your environment (21) with the installed Tutor (22). It asks you to confirm the upgrade from Ulmo to Verawood, runs the release-specific upgrade steps once, regenerates the environment, builds any images that need building, then runs the initialisation jobs, which apply the database migrations. In Tutor v22's code there are no extra Ulmo-specific steps, so the work is mostly the migrations, which is why the pre-flight checks matter.

Custom images. If you rebuild images, you will run tutor config save before launch, and that updates the environment version. Launch then no longer knows you came from Ulmo, so run the upgrade step explicitly:

tutor config save
tutor images build all   # or list only the images you customise
tutor local upgrade --from=ulmo
tutor local launch

The upgrading page in the Tutor docs shows --from=teak in its Ulmo to Verawood example. For a platform that is on Ulmo, pass ulmo; both are accepted values.

Kubernetes. The same flow applies with tutor k8s launch, and tutor k8s upgrade --from=ulmo when you rebuild images. Push rebuilt images to your registry before launch.

Step 4: Rebuild the Meilisearch index

Tutor v22 moves Meilisearch to v1.36.0, which refuses to start on a database created by v1.8.4: the container restart-loops with a "database version (1.8.4) is incompatible" error. Meilisearch only holds a derived search index, so the fix from the Tutor changelog is to delete it and rebuild. If the initialisation step of launch stops on Meilisearch errors, do this and then run tutor local launch again:

tutor local stop
rm -rf "$(tutor config printroot)/data/meilisearch/data.ms"
tutor local start -d
tutor local do init
tutor local exec cms ./manage.py cms reindex_studio
tutor local exec cms ./manage.py cms reindex_course --active

On a large site the reindex takes a while, and search in Studio and the course catalogue stays incomplete until it finishes. Plan it inside the maintenance window. On Kubernetes, the index lives in the Meilisearch volume rather than a local folder, so clear it there.

Step 5: Verify the platform

1. Check that every container is running and none is restart-looping: tutor local status, then tutor local logs --tail=100 lms cms meilisearch.
2. Run the smoke tests. Tutor added a tutor local do tests job in v21.0.8 that checks sign-in and user management, course import and creation, enrollment, health checks and OAuth application creation. See tutor local do tests --help for the setup options.
3. As a learner, open a course, play a video, submit a problem and check the progress page.
4. As staff, open Studio, search for a course and a component, and open the new instructor dashboard. If you relied on a custom "Reports" tab, confirm it still appears.
5. Open the Legacy Libraries tab on the Studio home page and plan the migration of anything listed there.
6. Decide whether notifications and notification emails should stay on, and set the opt-out flags if not.

Rolling back, and staying current

Tutor does not support downgrades, and any major upgrade is final once the migrations have run. Rollback therefore means restoring the backup: stop the platform, reinstall Tutor v21 (pip install "tutor[full]>=21.0.0,<22.0.0"), restore the Tutor root from the copy, including the old Meilisearch data, and start it again. Reverting image tags alone will not work.

Verawood is the current named release, and the Open edX named release page lists Willow next, for December 2026. Build the next upgrade into your calendar now; our guide to LMS end-of-support planning explains how to schedule upgrades so you are never more than one release behind. If you are still deciding whether Open edX is the right platform, our Moodle vs Open edX comparison covers the operating trade-offs.

How we can help

We plan and run Open edX upgrades on Tutor, including staging rehearsals, data fixes for failing migrations, plugin and MFE updates and the cut-over itself. See our Open edX services or our LMS development service if your platform also needs custom work.