Open edX legacy library migration to Content Libraries is a project
Migrating legacy libraries to Content Libraries moves reusable library content out of the deprecated library type and into Content Libraries, using the migration interface in Studio. The effort depends on three things: how many legacy libraries your platform holds, how many courses reference them, and how much of that content someone must check before learners see it. Those inputs set the schedule, so measure them before anyone estimates the work. The timing matters because Open edX Verawood is the current named release, published on 30 July 2026, and Open edX states that the latest named release is the only supported release and that it cannot support more than one release at a time. An operator that stays on an older release will eventually run unsupported software, so the move cannot be postponed indefinitely.
Start by confirming where your platform stands today. Record the Open edX release and the Tutor version you run, then read the Verawood release notes and the upgrade guidance for that release to see whether legacy libraries must be migrated before the upgrade or can wait until after it. Those documents set the order of work, and your timeline depends on that answer. Also confirm which team owns the upgrade decision, who approves changes to live courses, and whether any custom XBlocks, plugins or reporting queries read legacy library identifiers. Each of these dependencies can add work that a library count will not reveal on its own, so raise them before the plan is written.
Build the inventory before you choose a method. For each legacy library, record its owner, its content mix, the courses that reference it, the date of its last edit and any learner-facing use. Course references are the part teams most often underestimate, because a library can look idle in Studio while a live course still pulls content from it. Use the inventory to group libraries into batches. Libraries that one owner edits and no course references can move first. Libraries referenced across several courses or departments need a named reviewer and a rollback plan. Decide whether each migrated library keeps its original roles, and whether your team will use the tagging and taxonomy management added in Verawood for the new libraries, since that choice affects how authors find content after the move. Write these decisions down before the first migration run.
Verification takes most of the effort, and it repeats for every batch. After migration, someone must open each referencing course in a staging copy, check that library content renders, that problems still grade as expected, and that links and images resolve. Test against a copy of production data, since content problems often appear only in live course structures. These checks are one-time for the upgrade, but they repeat for each batch and for any course authored after cutover. When you request a quote, ask for a scope that lists the inventory output, the number of batches, the review steps per course, the test environments needed and the sign-off owner. Also confirm in the Open edX documentation for your release how the migration handles content it cannot convert, and reserve time to fix those items by hand.
What maps cleanly from legacy libraries and what needs manual review
This table compares legacy library capabilities with their Content Libraries equivalents during the Verawood upgrade. Read each row as a planning checkpoint: the notes say what to verify in the Verawood release notes or the Studio migration documentation before you run a migration. The main takeaway is that containers, course references and custom component types each need a test migration on a copy of your data.
| Source capability | Platform equivalent | Migration notes |
|---|---|---|
| Library container | Content Library in Studio | Confirm in the Studio migration documentation how the migration UI maps each legacy library to a Content Library and how it names the result. Record original library identifiers before you start. |
| Standard components inside the library | Equivalent library components of the same type | Most standard component types are expected to carry over, but confirm each type against the documentation. Render a sample of each on a staging copy before accepting the output. |
| Custom XBlock components in the library | Same XBlock type installed on the Verawood instance | Conversion alone does not settle this. The XBlock must be installed, compatible with Verawood and supported for library use. Plan manual review and testing for each one. |
| Course references to library content | Library content blocks that point to a Content Library | Confirm whether existing course references update automatically or need re-linking. Test at least one course that uses library content on staging before the production run. |
| Library permissions and roles | Content Library team roles in Studio | Do not assume legacy access grants carry over one to one. Confirm how each role migrates, then reassign any access that did not transfer and document who holds it. |
| Tags and metadata | Tagging and taxonomy management added in Verawood | Verawood added tagging and taxonomy management. Confirm whether legacy metadata moves into taxonomies or stays as free text, and clean up tag names before go-live. |
| Unpublished drafts and pending edits | Draft and published states in Content Libraries | Confirm whether unpublished drafts migrate and whether content must be published before learners see changes. Agree the publishing step with content owners before the cutover. |
How course references to legacy libraries change during the move
Before a legacy library is migrated, the first question is which courses depend on it. A course that uses library content does not hold its own copy of those components. It points at the library, and learners see that content inside the course. This dependency is what makes the move risky. If a library is converted or retired while a course still points at it, the course can lose content without showing an error in its own structure. Each referencing course should be treated as a dependent system with its own owner, its own release schedule and its own test plan.
Finding referencing courses before migration is a discovery task. The goal is a complete list of course runs that use content from each legacy library, with the library name, the course owner and the current state of the run. Confirm with your Open edX operations team how your installation lets you identify these courses, because the supplied material does not describe a built-in report. Where no automated method is confirmed, build the list from course exports or from a review of each course in Studio. Record every course that uses library content as part of discovery, including draft runs, archived courses and courses an instructor is still building.
Verifying courses afterward is a different job from discovery. Once libraries have been migrated, the question is whether each recorded course still shows the content it showed before. Use the discovery list as the test set. For each course run, open it in Studio, confirm that the components which came from a library are present and display correctly, and check that units that worked before still work. Confirm with the Verawood release notes and your vendor which reference behaviors changed, so that your checks target the right risks. Run the same checks on a staging copy before any production course is touched.
Plan the decisions that the checks will create. Assign a sign-off owner for each course, decide what happens to a course that fails verification, and agree whether courses with active learners need a change window. Courses in draft or archived states are easy to forget, so give them an explicit owner and a status in the record. Keep a per-course result for every run, including the date of the check and the person who approved it. That record is the evidence you will need if a learner or instructor reports missing content after the move.
Which documented tools and Studio paths support the migration
The migration relies on four documented pieces: the Studio migration UI, Studio views for locating course references, the Verawood release notes that define the target, and Tutor for running the result. Each card below explains what the item covers and what your team should confirm in its own environment before scheduling work.
Studio migration UI for legacy libraries
This is the Studio interface for converting deprecated legacy libraries into Content Libraries. It is the main path for moving library content during the Verawood upgrade, so it sets the order of work: inventory first, then conversion, then verification. Confirm in your Verawood build where the migration action appears, whether it runs per library or in batches, which library content it converts, and what it leaves for manual rework. Record the exact steps in your runbook so reviewers can repeat them.
Studio views for course references
Studio views let course teams locate courses that reference library content before any library changes are made. Use them to build the list of affected courses, including courses that teams rarely edit, because a converted library can break a course that still points to the old library identifier. Confirm which views your build exposes, how they report references, and whether they cover archived course runs. Keep the output in your migration tracker so each course owner can sign off.
Verawood release notes
The Verawood release notes define the target release for this migration and list changes that touch Studio, including the new Studio sidebar, tagging and taxonomy management, and new frontend plugin slots. Verawood was published on 30 July 2026 and is the current named release. Read the library and migration sections against your own customizations, such as custom XBlocks or theme code that depends on Studio pages. Confirm the upgrade notes that apply to your starting release before fixing the target build.
Tutor for the Docker-based deployment
Tutor is the official Docker-based Open edX distribution for production and local development, and it supports Kubernetes deployments and plugins. Use it to build the Verawood environment, then rehearse the library migration on a staging copy before production. Check that your plugins and hooks are compatible with Verawood, that image versions match the release you planned, and that database backups exist before the upgrade starts. Confirm the exact Tutor version to pin with your deployment owner.
Single supported release constraint
Open edX states that only the latest named release is supported and that it cannot support more than one release at a time. This means the migration should land on Verawood directly, with the source platform brought to a state the Verawood upgrade path accepts. Plan the library migration as one step in that sequence. Confirm with your platform owner which intermediate steps the documentation requires for your current release, and whether a later release, such as Willow, is expected to arrive before your work finishes.
What the migration sequence looks like from inventory to decommission
The sequence moves legacy libraries from inventory to decommissioning in stages, so each stage produces evidence before the next one starts. Named sign-offs at each stage, plus a pilot and a parallel run, catch problems before learners reach migrated content. Confirm the exact steps and tooling with your Open edX provider before you start.
Inventory legacy libraries and referencing courses
Your team lists every legacy library in the instance, then maps each course that references content from those libraries. The output is a register with library identifiers, owning course teams, referencing courses and any library content shared across several courses. Platform operations and course owners review the register together. The step is done when every legacy library has a named owner, every referencing course is accounted for, and the list is frozen as the baseline for later comparisons. Ask your provider how they expect this inventory to be generated for your release, and confirm which reports exist in your environment.
Run a pilot migration on an instance copy
Your team or DeployOpen takes a copy of the production instance and runs the Studio migration UI against a selected set of libraries from the register. The selection should include both simple and complex cases, such as libraries referenced by several courses. The team records what converted cleanly, what needed manual rework and which course references broke. The output is a pilot report and a fix list to clear before the real run. The platform owner and the course owners of the pilot courses sign off on the report. Confirm with your provider whether the copy must match the production release and how the copy is isolated from learners.
Verify migrated libraries in a parallel run
Migrated libraries are made available alongside the legacy ones in a non-learner environment, so course teams can open each referencing course and compare content component by component. Teams log discrepancies in a shared tracker, each with a severity level and an owner. The output is a verified list of libraries and a defect log in which every item is either closed or accepted as a known difference. Course owners sign off per course, and the platform owner signs off the full set. Confirm with your provider whether your instance can run both versions side by side or whether you need a separate staging environment for this stage.
Schedule and execute the cutover window
Plan a cutover window that covers the Verawood upgrade and the migration of verified libraries to Content Libraries. Freeze authoring for affected courses, take a verified backup of the database and media storage, apply the upgrade, run the migration and then reopen access. The output is a cutover runbook with go or no-go checks and a defined rollback decision point. The change approver and platform owner sign off the start of the window, and course owners confirm their courses load afterward. Verawood is the current named release, and Open edX supports only the latest named release, so confirm the upgrade path and any breaking changes with your provider before you book the window.
Confirm courses render after cutover
After the cutover, the team repeats the reference checks from the inventory against the live instance. Each referencing course is opened in Studio and in the LMS, and the team confirms that library components display, load and resolve correctly for authors and learners. Results are recorded against the register, line by line. The step is done when every referencing course is marked verified or has a logged fix with a named owner. Course owners and the platform owner sign off. Agree the length of the post-cutover watch period with your provider and your operations team before the cutover begins.
Decommission legacy library references
Once courses are verified, remove the remaining references to legacy libraries and retire the legacy library records. The team archives the inventory, pilot report, parallel-run defect log and cutover runbook as an audit trail. The output is a closure report listing removed references, retired libraries and where each piece of evidence is stored. The platform owner and compliance lead sign off that the evidence meets your internal retention rules. Confirm with your provider how retired library data is handled, and check how long backups are kept under your own data retention policy before you remove anything.
What drives the cost and duration of a library migration
This table lists the factors that change the effort of a legacy library migration and the detail to request in a quote. Use it to check which factors apply to your libraries, courses and environments before you compare proposals. Quotes follow from a written scope, and DeployOpen does not publish a price list.
| Driver | Effect on effort | What to ask for in a quote |
|---|---|---|
| Number of legacy libraries | Each library needs an inventory entry, a target Content Library and a content check | Library count, and whether the inventory step is included in scope |
| Courses that reference library content | Each referencing course needs a post-migration check, which adds review time | Count of courses per library and the checks included in the fixed scope |
| Content volume per library | Larger libraries take longer to move, verify and re-check in Studio | Component count and types per library, and any content that needs manual rework |
| Custom XBlocks or customizations using library behavior | Code that reads or writes legacy library structures needs changes and tests before cutover | List of custom XBlocks and plugins, and whether they call library behavior |
| Number of environments | Development, staging and production each repeat the migration and verification | Environments in scope, and whether the migration runs once per environment or is promoted |
| Approval and testing requirements | Sign-off gates, test plans and evidence retention add review cycles to each environment | Who approves, which tests are required, and the evidence format expected |
| In-house Open edX operators | Teams that already run Tutor and Studio need less onboarding and handover work | Operator skills covered, and what knowledge transfer and runbooks are included |
| Timing relative to the Verawood upgrade | Running alongside the Verawood upgrade may share test cycles, or add changes to them | Confirmed target release, and whether the upgrade and migration sit in one scope |
What usually goes wrong with library migrations and how to prevent it
Most legacy library migrations to Content Libraries run into the same five risks. Each one maps to a decision the migration team controls, from the inventory it builds to the release date it plans against. Treat the prevention steps as entry criteria for the cutover.
Courses that reference unknown libraries
Legacy libraries are often linked from course content by someone who has since left the team, so the platform owner may not know which courses depend on them. Build an inventory before any migration starts: export every course, search for legacy library references in units and problems, and record the owning course team for each. Ask course teams to confirm any library they use that the inventory does not show. Treat unlisted references as blockers until they are resolved.
Migrating during a live term
Learners who are mid-course may see library content change between sessions, and instructors may edit the same units while the move is underway. Set a fixed cutover window outside an active term, and ask course teams to freeze edits on affected courses for that window. Confirm the window against your academic calendar and with your support desk before scheduling. Plan a rollback point so the team can reverse a failed batch without losing edits made after the freeze lifts.
Course teams skipping verification
Migration tools move content, but only course teams can judge whether a migrated unit still teaches what it should. Without a written checklist, verification often becomes a quick look at the course outline. Give each team a short checklist covering every migrated component, its learner-facing text, graded problems, and any scores or due dates that depend on them. Record sign-off per course, and hold the cutover for any course that has not returned it.
Customizations that assume legacy structure
Custom XBlocks, theme templates, reports and scripts may read library content through the legacy structure, so they can fail or report wrong data after the move. Search your code and reporting queries for legacy library identifiers and for assumptions about how library content is stored. Test each finding against the pilot copy and assign an owner to each one. Start these fixes early, since code changes can take longer than the content move itself.
Pilot run without production data
A pilot on an empty or synthetic instance shows that the migration runs, but not how it behaves on your real course volume and library reuse. Run the pilot on a recent copy of production data, using a small set of courses that cover shared libraries, custom code and a live-term case. Record each failure and its fix, then update the runbook before the full cutover. Confirm that the pilot copy runs the same plugins and theme as production.
Questions teams ask before migrating legacy libraries to Content Libraries
What drives the cost of migrating legacy libraries to Content Libraries?
The main cost drivers are the number of legacy libraries, the number of components in each, how many courses reference them, and how much converted content needs manual review. Most of the spend is people time: course authors checking converted content, operators preparing the platform, and an implementation team if you hire one. Environment work, such as a staging copy of your Open edX instance and test accounts, adds to the total. Most of this effort is one-time. Recurring costs appear only if you add ongoing support or a retainer after go-live.
Ask a partner for: the inventory method, the assumed count of libraries and courses, the review included per library, how work is split between your team and the partner, and which items sit outside the fixed scope.
How long does a legacy library migration take?
No single duration applies to every platform, so treat any timeline as dependent on your own environment. The main variables are the size of your library inventory, how many courses reference those libraries, how many components need manual rework, and how quickly authors and reviewers can respond. Your hosting setup matters too: the time to build a staging environment that mirrors production, the upgrade path from your current release to Verawood, and your change-approval process. Ask for a timeline built from a written inventory, and confirm the upgrade steps against the Verawood release notes before you commit to dates.
Can our own team migrate legacy libraries with the Studio migration UI?
Yes, a team with Open edX operations experience can run the migration itself, provided it has the access, time and review capacity for the work. The Studio migration UI is the route for moving legacy library content into Content Libraries, so start by reading the instructions for your target release. Whether to do it internally depends on how many libraries you have, how complex they are, and whether your Studio staff can test results against live course content. Teams that lack staging capacity or cannot assign authors to review converted content often hand that part of the work to a fixed-scope partner. Confirm which steps the UI covers in your release before you plan the split.
What does a library migration need from course authors and operators?
Authors need to review converted library content in each course that uses it, confirm that problems, videos and text still display as intended, and flag any content that needs rewriting. Their time is usually the least predictable input, so name reviewers and agree on a sign-off step before the work starts. Operators need to schedule a staging copy, confirm backups of course and library data, plan the platform upgrade window, and grant Studio access to the people running the migration. They also own the rollback plan and the post-migration check on learner-facing courses. Ask your partner which steps they expect your staff to perform and which they will perform themselves.
How does the Verawood release timing affect a library migration plan?
Verawood is the current named release, published on 30 July 2026, and Open edX supports only the latest named release. If you run an earlier release, the library migration is tied to your upgrade to Verawood, so the two projects should be planned together. The next releases, Willow and Xylon, are listed for December 2026 and June 2027. Plan a freeze window that starts after the Verawood upgrade is tested, and check the release notes before scheduling large content changes near the next release cycle. Because older releases do not receive upstream support, delaying the upgrade extends your exposure. Confirm the exact steps and deprecation timing in the Verawood release notes.
What happens to courses that reference legacy libraries after migration?
Courses that use a library pull its content into their units, so migrating the library does not by itself confirm that each course still behaves correctly. Check every course that points to a migrated library in staging: whether the references resolve, whether learners see the expected components, whether grading and gating still work, and whether any course edited after migration now shows stale content. Courses that are archived or rarely used need a separate decision about whether they stay on the old data. Ask how the migration documentation handles references, build a list of affected courses from the inventory before you start, and keep a record of each check so course owners and auditors can see what was tested.
What should we ask a partner to include in a migration quote?
Ask for the scope in writing before work starts, since most DeployOpen engagements are fixed-scope and agreed in writing. The quote should list the inventory of libraries and courses in scope, the staging and test steps, the review method for each library, who performs author review and who performs operator steps, the rollback plan, the handover documentation, and the exclusions. Ask whether post-go-live support is a separate retainer. DeployOpen does not publish a price list, so the quote follows from the written scope. Compare quotes only when they share the same inventory and assumptions.
How DeployOpen scopes, delivers and supports a library migration
DeployOpen plans and delivers legacy library migration to Content Libraries as a defined piece of work inside infrastructure you control, tied to the Verawood upgrade and the Studio migration tooling. Most engagements are fixed-scope, so the library inventory, course checks and acceptance criteria are agreed in writing before work starts.
How we scope
- Written scope lists the Open edX instances, Studio sites and libraries included in the migration.
- Inventory of legacy libraries and the courses that reference each one, agreed before any changes.
- Confirm the Verawood upgrade target, your current release and the library types in use.
How we build
- Run the Studio migration UI against each legacy library in a non-production copy first.
- Review each migrated library's components and problem content for loss or changed behavior.
- Check every course that references library content, so imported blocks still resolve for learners.
How we hand over
- Written record of which libraries migrated, which were left in place and why.
- Course checklist showing each referencing course, its check result and any follow-up owner.
- Runbook for your team to repeat the checks on new content and later upgrades.
How we support
- Optional retainer covers questions, fixes and follow-up checks after handover, agreed in writing.
- Confirm with Open edX documentation and your hosting team which Verawood changes affect your libraries.
- Re-run library and course checks when you add content or plan the next named release.
