Upgrade Open edX from any old release to Verawood with Tutor, one release at a time

You cannot skip named releases. Cubite runs managed Open edX from $1,260 a month for up to 1,000 concurrent learners, and named-release upgrades are included in every managed tier. This runbook is for teams that upgrade their own Tutor installation: it takes a site from Lilac, or any later release, to Verawood one release at a time, with the Tutor version for each hop, what breaks, the checks to run after each hop and the way back.

Short answer (updated October 26, 2026): each Open edX named release has its own Tutor major version, from Tutor 12 for Lilac to Tutor 22 for Verawood, so going from Lilac to Verawood takes ten hops, one release at a time. For each hop, back up the platform, install the next Tutor major, run the launch command, then check that your counts of users, enrollments and certificates have not dropped. Tutor does not support downgrading, so the backup you take before each hop is your rollback.

As of October 26, 2026, Verawood (released July 30, 2026, on Tutor 22) is the only supported Open edX release. Willow, the next one, is planned for a release cut in early January 2027 and a release in late February 2027, as the Build-Test-Release working group confirmed on October 5, 2026. The Open edX release table lists every release with its Tutor version and support status, and Cubite's free upgrade-path checker lists the hops from your release.

Why you cannot skip a named release

Open edX periodically squashes its Django database migrations, so a database has to pass through each release in turn, and Tutor's upgrade steps, such as the MongoDB version upgrades, are written per release. Tutor's upgrade guide describes moving "from one major version to the next" and warns that "any upgrade is final because downgrading is not supported". When Aulasneo took a client from Lilac to Ulmo, nine releases in one maintenance window, the team built a minimal Docker image for each release from Koa onward just to run the migrations (their write-up on the Open edX forum, September 1, 2026).

Before the first hop

One hop, step by step

1. Stop the platform and back up the whole Tutor root, the single folder where Tutor keeps the configuration, the environment and the data: tutor local stop, then sudo rsync -avr "$(tutor config printroot)/" /var/backups/tutor-before-maple/. Name the folder after the release you are moving to, and keep a copy off the server.
2. If MySQL or MongoDB run outside Tutor, back them up with your provider's tools as well: they are not in the Tutor root.
3. Install the next Tutor major and nothing newer, for example pip install "tutor[full]~=13.0" for Maple, the same range as Tutor's own pins (the table below gives the major for each hop). Upgrade your own plugins to releases built for that major.
4. Run tutor local launch (tutor local quickstart on Tutor 14 and earlier). Tutor sees that the environment was generated by the older release and runs that release's upgrade steps once.
5. If you build custom images, those steps are skipped once you have run tutor config save, so run them yourself: tutor config save, tutor images build openedx (plus any other image you customize), tutor local upgrade --from=lilac with the release you are leaving, then tutor local launch (quickstart on Tutor 14 and earlier).
6. Run the row-count check and the checks for that hop in the table, then start the next hop.

Every hop from Koa to Verawood

Each row is one hop. The Tutor column is the major to install for it: pip install "tutor[full]~=N.0" picks that major's latest patch, the same range that Tutor's table of older releases pins. The middle column is a selection of the changes in Tutor's changelog, most of them marked as breaking, plus what Tutor's upgrade step does for that release and, where noted, what changes in the release itself; read the full list against your own plugins and customizations.

On the Ulmo to Verawood hop, Meilisearch 1.36 restart-loops on the old index ("database version (1.8.4) is incompatible with your current engine version (1.36.0)"), so rebuild the index during that hop, as Tutor's changelog gives it: stop the platform, delete the old index, start it, re-run init, then reindex Studio and the active courses: 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 and tutor local exec cms ./manage.py cms reindex_course --active. On a large site the reindex takes a while, and search stays incomplete until it finishes. For Verawood's own changes beyond Tutor, see what is new and what breaks in Verawood.

Verawood's Developer and Operator Release Notes also list two migrations that can stop on old data, and a default that changed:

• The split_modulestore_django migration 0004_courseid_unique_ci fails with an IntegrityError if two course IDs differ only in letter case: delete the invalid course record as the notes describe, then re-run the migrations.
• The new catalog backfill fails with a ValueError if a course's organization short code is missing from the Organizations table: create the missing Organization record in Django admin, then re-run the migrations.
• Notifications and notification emails are on by default; to keep them off, enable the notifications.disable_notifications or notifications.disable_email_notifications flag.

On a release older than Koa: Tutor's table of older releases starts at Koa (Tutor 11), and its upgrade command carries steps back to Ironwood, so the same one-release-at-a-time rule applies from there. A site that was installed without Tutor has to move onto Tutor first, which is a project of its own.

After every hop: count users, enrollments and certificates

An upgrade should not remove accounts, enrollments or certificates, so three counts are a quick check that a hop kept your data. Take them before the first hop, on the staging copy and again at the start of the production window, and after every hop: none of the three may drop. Tutor's init can add a service account, so a small rise in users is expected: at the Lilac to Maple hop, Tutor 13's init creates one called cms. The counts come from the auth_user, student_courseenrollment and certificates_generatedcertificate tables, in the database Tutor names in OPENEDX_MYSQL_DATABASE (openedx by default). With Tutor's own MySQL, this command runs the count in the mysql container, in the same pattern as Tutor's database-dump command:

tutor local exec -e USERNAME="$(tutor config printvalue MYSQL_ROOT_USERNAME)" -e PASSWORD="$(tutor config printvalue MYSQL_ROOT_PASSWORD)" -e DB="$(tutor config printvalue OPENEDX_MYSQL_DATABASE)" mysql sh -c 'mysql --user=$USERNAME --password=$PASSWORD $DB -e "SELECT (SELECT COUNT(*) FROM auth_user) AS users, (SELECT COUNT(*) FROM student_courseenrollment) AS enrollments, (SELECT COUNT(*) FROM certificates_generatedcertificate) AS certificates"'

If a number drops, stop: restore the backup from before that hop, and find the cause on staging before you try the hop again.

Rollback

Tutor does not support downgrading, so a failed hop is rolled back from the backup you took before it: stop the platform and restore the backed-up Tutor root with --delete, so that files the newer release wrote, such as a MySQL 8 data directory or a Meilisearch 1.36 index, do not survive: sudo rsync -a --delete /var/backups/tutor-before-maple/ "$(tutor config printroot)/". Then reinstall the Tutor major you were on and start the platform with tutor local start -d. Restore any MySQL or MongoDB that runs outside Tutor from its own backup at the same time. Coming back from Verawood, the old search index has to come from that backup too: Tutor's changelog notes that Meilisearch 1.8.4 cannot read an index written by 1.36.0. Rehearse the restore on staging before the production window, so you know how long it takes.

Lessons from a nine-release upgrade

A detailed recent account on the Open edX forum is Aulasneo's Lilac to Ulmo upgrade (discuss #19509, September 1, 2026), done in a one-hour window after two months of preparation. What cost them the most time:

• Squashed migrations: they could not skip releases, so they built a minimal Docker image per release from Koa onward just to run the migrations.
• Converting every table to utf8mb4 was the single longest step.
• MongoDB held 500 GB, almost all of it video in GridFS, because that is where Studio's course file uploads go.
• After Sumac, the forum migration needed FORUM_MONGODB_DATABASE patched back in.
• Teak's Meilisearch reindex stalled init on a small instance.

Do it yourself, or have it managed

Cubite is one of the managed options and publishes this runbook. Named-release upgrades are included in every managed Open edX tier (Lean $1,260 a month, Resilient $1,850 a month, Scale from $3,400 a month), each rehearsed on a UAT environment before production. See managed Open edX. A platform Cubite takes over starts on the release it already runs, and bringing it up from an unsupported release is a fixed quote agreed before the managed term starts. If you keep the upgrade in-house but need a plugin, theme or XBlock ported to a new release, see Open edX development.