How to plan a Moodle 3.x to 4.x upgrade in steps
A Moodle 3.9 or 3.11 site reaches a supported release in hops, and each hop has its own minimum starting version, PHP version and database requirement. Plan the sequence backward from the target release, then confirm every step against that release's notes before you book an upgrade window on infrastructure you control. The reason the path runs through 4.x is version gating in the newer releases. Moodle 5.1 requires sites to be on Moodle 4.2.3 or later, and Moodle 5.3 requires 4.4 or later. A site still on 3.x cannot move directly to either release, so the 4.x releases are stepping stones. Moodle 4.5 is the current long-term support release, available from 7 October 2024 with security support until 4 October 2027. For many organizations that is the first 4.x destination, and the choice between stopping there and continuing to 5.x is a decision to make early because it sets the PHP and database versions you must install along the way.
The exact minimum starting version for each 4.x hop comes from that release's own notes, and you must confirm it before scheduling. Do not assume that each hop accepts the previous minor version without checking. Build a written hop table with four columns: source version, target version, required PHP version, and required database version. Fill each row from the official release notes, not from memory or from a forum thread, and record the date you checked. This table becomes the basis for your environment rebuilds, your test plan and the approval you need from the business owners. PHP and database work often drives the timeline more than the Moodle code itself. Moodle 5.1 requires 64-bit PHP 8.2 or later and PostgreSQL 15, MySQL 8.4, MariaDB 10.11 or SQL Server 2017 or later. Moodle 5.3 requires 64-bit PHP 8.3 or later, PostgreSQL 17, MySQL 8.4, MariaDB 11.4 or SQL Server 2019 or later. Check whether your operating system packages and your current database server can reach these versions, and whether your application hosts or managed database services support them. If they cannot, the platform upgrade must come first. Also note that from Moodle 5.1 the web server document root must point to the new /public directory, so your reverse proxy and virtual host configuration belong in the plan.
Plugins and content are the second group of risks. Inventory every installed plugin, theme and custom code change, and record the version each one supports. Check each one against the target release before the first test run, and identify which ones have no compatible version and need a replacement or removal decision. The 4.x redesign also changes navigation and the course index, so theme customizations and any custom templates need review, not just a version check. Plan a test restore of a recent production copy into an isolated environment, run each hop there, and keep a rollback point before every step. Agree with your academic and administrative owners which courses, question banks and reports must be checked by hand after each hop. Two sibling pages cover the details you will need. The Moodle 4.1 LTS to 4.5 LTS upgrade page covers the 4.1.2 starting point, the PHP and database jumps, plugin compatibility checks and the changes users will notice. The Moodle 5.0 upgrade and removed features page lists the features that are gone in 5.0 and later and the content that must be checked before you move past 4.x. Use both pages when you finalize the hop table. When you request a quote, provide the hop table, the plugin inventory and your hosting constraints so the scope can be written with clear checkpoints and deliverables.
Which Moodle changes break 3.x sites and what to check
This table lists the Moodle changes most likely to disrupt a 3.9 or 3.11 site on the way to 4.x, the impact of each, and the check to complete before cutover. Read it as a checklist for every hop, not a single jump. Where the full 4.x change list is not confirmed here, the action names the release notes to check for that hop.
| Change | Impact | Action needed |
|---|---|---|
| Redesigned navigation and course index | Students and teachers find menus, the course index and drawers in different places, so training material and help pages go out of date | Confirm the navigation changes for each 4.x hop in the release notes, then walk a sample of teachers and students through a staging copy |
| PHP version requirements | Each hop can require a newer PHP version, and a host that runs 3.x may not run the target release | Confirm the PHP minimum for each hop in the release notes and upgrade PHP on staging before the code upgrade |
| Database server requirements | Database engine minimums change between releases; Moodle 5.1 lists PostgreSQL 15, MySQL 8.4, MariaDB 10.11 and SQL Server 2017, and 5.3 lists PostgreSQL 17, MySQL 8.4, MariaDB 11.4 and SQL Server 2019 (Moodle 5.1 and 5.3 release notes) | Confirm the database minimum for each 4.x hop and plan database upgrades ahead of the code upgrade if the path continues beyond 4.x |
| Minimum starting version for each hop | Moodle 5.1 requires sites on 4.2.3 or later, and 5.3 requires 4.4 or later, so a 3.x site must pass through intermediate releases | Map the upgrade as sequential hops, confirm each minimum in the release notes, and do not plan a direct jump |
| Plugin compatibility | Third-party plugins written for 3.x may fail to install or may break pages, and blocks, themes and authentication plugins fail most often | Check each plugin's listed supported Moodle versions for every target release, then replace, update or remove unsupported plugins and record each decision |
| Classic theme removal in 5.3 | Moodle 5.3 removes the Classic theme from core, so sites that carry it forward lose their theme at that hop | Identify sites and custom themes that depend on Classic and plan a theme migration before the 5.3 hop |
| Web server document root from 5.1 | The document root must point to the /public directory, otherwise the site can show directory listings or errors | Update the web server configuration in the cutover runbook for the 5.1 hop and test routing on staging |
| SSO and authentication plugins | Single sign-on plugins such as SAML2 list a range of supported Moodle versions, and a version mismatch can block all logins | Confirm the SSO plugin version supports each target release and test a full login, logout and user-creation cycle before cutover |
What to prepare before the first hop starts
Four items need to be ready before the first hop starts, and each one feeds the next. The backup gives you a rollback point, the plugin and code registers show what the upgrade will touch, and the staging copy is where every hop is rehearsed. The server stack (PHP, database and web server) must also be assessed for each hop, because the requirements change along the path.
Full backup with a tested restore
Take a complete backup of the Moodle database and the moodledata directory before any hop begins. A backup only counts once someone has restored it onto a separate server and confirmed that courses, files and user accounts come back intact. Record the Moodle version, PHP version and database engine at the time of backup so the rollback point is clear. Owner: the client's Moodle administrator, working with the database administrator. Artifact: a backup set and a signed restore test record.
Plugin inventory mapped to target release
List every installed plugin with its name, plugin type, installed version and source, then check each one against the release the current hop targets. Plugins without a version compatible with that release need a replacement, an upgrade or a documented decision to remove them. Confirm compatibility with the plugin's own release notes and the Moodle plugins directory, not with memory of earlier versions. Owner: the client's Moodle administrator, with the business owner approving any removal. Artifact: a plugin register with a target-version column and a decision for each row.
Custom themes, local code and overrides
Identify every custom theme, local plugin, modified core file and template override, since these are the items most likely to break when core code changes. Record where each one lives, who wrote it and whether it still serves a current requirement. A theme built on a parent theme that is removed or replaced in a later release needs its own rebuild plan. Owner: the client's development lead, or the vendor that built the code. Artifact: a code register listing each customization, its purpose, its owner and its upgrade action.
Staging environment from recent production data
Build a staging environment on the same server stack as production, then restore a recent copy of the production database and moodledata into it. Isolate staging from live email, external integrations and single sign-on callbacks so test activity cannot reach real users or systems. Keep the stack in staging aligned with the requirements confirmed for the hop being rehearsed. Owner: the client's infrastructure team. Artifact: a staging environment with a dated copy of production data and a documented rebuild procedure.
How each 4.x hop sets the next starting point
The Moodle 3.x to 4.x upgrade is a chain, not a single jump. Each hop has a minimum starting version, and that minimum often comes with a minimum PHP version and a minimum database version. A site on 3.9 or 3.11 may therefore need one or more intermediate upgrades, plus server changes, before the installer will accept the next step. Your first task is to find out how many hops your site needs and what each one demands of the stack, because the answer changes the schedule, the staffing and the number of backups you will take. The release notes for each 4.x release on your path are the source for those minimums. For each release, record the starting version the upgrade accepts, the PHP version and the supported database versions, any web server or operating system changes, and any removed features or plugins that block the upgrade. Copy the exact version numbers and note the date you checked them. Do not assume that a point release left the requirements unchanged. Confirm each figure against the release notes for the version you are moving to, and ask your partner or Moodle HQ to confirm any figure that is unclear.
The destination is set by the 5.x requirements. Moodle 4.5 is a long-term support release from 7 October 2024, with security support until 4 October 2027. Moodle 5.1 requires sites to be on Moodle 4.2.3 or later, and Moodle 5.3 requires sites to be on Moodle 4.4 or later. Those rules mean a site that stops at 4.5 can move on to 5.3 without an extra hop, while a site that stops earlier may need one more step. Decide early whether 4.5 is the final destination for this migration or a waypoint toward a later 5.x release, since the 5.1 change to the web server document root and its PHP 8.2 minimum add work that 4.x does not require. Write the complete path down before anyone schedules downtime. A usable plan lists each hop with its starting version, target version, PHP and database minimums, web server changes, plugin blockers, the backup taken before it, the person who signs off the step and the date each minimum was confirmed. Illustrative example: if a site on 3.9 meets the starting version for the first 4.x hop but not the PHP version it requires, the plan needs a server change ahead of that hop, and the outage window must cover it. A path written this way shows where the risk sits and whether the schedule holds.
Treat the written path as a dependency record, not a draft. Review it with the teams that own the database, the web servers and the plugins, because each of them can block a hop. Re-check the minimums just before the window opens, since point releases can change the notes. Only when every hop has a confirmed starting version and a confirmed stack is it safe to book downtime and communicate dates to course owners.
The upgrade sequence for each hop, with checks and rollback points
This sequence moves a Moodle 3.x site through each 4.x hop in order, with a check and a rollback point at every stage. Each hop is rehearsed on a copy of production before the live site changes, so cutover repeats a procedure that has already been tested. The output is a verified path from the starting version to the chosen target.
Freeze changes and announce the window
The site owner and the Moodle administrator agree a change freeze covering course edits, user imports, plugin installs, theme changes and admin settings. Teachers, students and support staff receive a written notice with the start and end of the window. The freeze is done when it is recorded in the change log, the notice has been acknowledged by each stakeholder group, and the freeze has been applied to the production site.
Take and verify backups
Take a full database dump, a copy of the moodledata directory, the code tree, the config file and a list of installed plugins with their versions. Restore the database dump to a separate database and compare table counts and a sample of course, user and grade records against the source. The step is done when a restore has actually been tested, not only when the backup job reports success, and the backup set is stored off the server being upgraded. Confirm backup tooling and retention with your database administrator.
Change PHP and web server in staging
Build a staging stack that matches the requirements listed in the release notes for the target hop, including the PHP version, required extensions, database engine and version, and web server modules. Save the current PHP and web server configuration before editing it, so each can be reverted separately from the database. Check that the web server serves the Moodle directory, that PHP runs the required extensions, and that the Moodle environment page reports no blocking errors on an empty site. Do not change production PHP or the web server until this staging check passes.
Run the hop on a copy of production
Restore the verified backup to a copy of production, point the staging stack at it, and run the upgrade for this hop only, through the administration interface or the command-line upgrade script. Record the start and end times, every error and warning in the upgrade output, and the version numbers reported after completion. The step is done when the upgrade finishes without fatal errors and the administration dashboard loads. Keep this copy as the reference for the checks that follow.
Fix plugin and theme incompatibilities
Compare each installed plugin against the target hop and confirm a compatible version exists. Update, replace or remove each one, and test custom themes and layout overrides page by page. Record each replacement with its source, the reason for the change and the person who approved it, because plugin changes are a common source of faults after upgrade. The step is done when every plugin reports a compatible version, no dependency errors remain, and the replacement list is signed off by the site owner. Confirm replacement plugins with their maintainers.
Run the hop-level checks
Test the upgraded copy with named accounts for each role. Check login through every enabled authentication method, course access for a teacher and a student, grade reports against a pre-upgrade export, a quiz attempt through to grading review, file upload and download, and cron running the scheduled tasks on time. Record a pass or fail for each check. The step is done when every check passes, and any failure has a ticket and an owner. A failed check stops the hop.
Record a rollback point
Once this hop passes, take a labeled backup of the upgraded copy: database, moodledata, code tree, config file, and the PHP and web server configuration. Record the Moodle version, PHP version, database version and plugin list. Write the restore steps and rehearse them on a separate database. The step is done when the rollback set is stored apart from the site and the restore has been tested. If cutover fails, the team returns to this point.
Repeat the sequence for the next hop
If the target is more than one hop away, return to the PHP and web server stage with the upgraded copy as the new starting point. Confirm the requirements for each hop in its release notes, and run each hop on its own copy with the same checks and rollback point. Do not combine hops on production. Once the final hop passes, schedule the production run in the approved window. The step is done when the cutover plan names the rollback point it depends on and every hop has a recorded result.
How to test each hop and roll back if it fails
A hop is complete only when the test set passes on the upgraded copy and a sample of real courses has been checked by users. The upgrade script finishing is not a sign-off. Build the test set before the first hop, run it against a staging copy restored from production, and repeat it after every hop. Admin tests should cover creating a course, enrolling users, changing roles, and checking the redesigned navigation and course index that changed in the 4.x releases. Teacher tests should cover adding and editing activities, exporting grades, backing up a course, and restoring that backup into a new course to confirm the file is valid.
Authentication needs its own tests because each method fails in a different way. For every method in use, test an actual login rather than only checking the configuration page. For LDAP, confirm the bind and user lookup. For LTI, launch a tool from the external system that sends users in. For OAuth 2, complete a sign-in with the provider. For SAML 2.0 through the auth_saml2 plugin, check attribute mapping, first-login account creation and logout. Confirm that each plugin version you run supports the target Moodle release before testing, since plugin support is stated per release. Then test file and media playback in activities and the content bank, and check the admin task log to confirm scheduled tasks run without errors.
Rollback means restoring the database and moodledata snapshot taken before the hop, together with the code that matched it. These three must be restored as one set. The database records the schema the code expects, and moodledata holds the files that the database points to. Restoring code alone leaves a database the old code cannot read. Restoring the database alone leaves an old schema running new code. Decide the rollback trigger before the hop starts: which test failures are blocking, how many user-reported faults in the sample are acceptable, and any authentication failure that stops staff from working. Name the person who makes that call.
A rollback is only as good as the restore you have rehearsed. A snapshot that has never been restored into an empty environment may be incomplete, mis-permissioned, or missing web server settings. Rehearse the full restore on a separate host at least once for each hop. Confirm that the site starts, users can log in, and the same test set passes. Check that the snapshot includes the database dump, the full moodledata directory, and the exact code version or archive. Ask your hosting or platform team to confirm how long a restore takes in your environment and who can carry it out outside business hours.
Do not mark a hop complete when the test set passes. Choose a sample of real courses from different departments, including courses with quizzes, large question banks, video content, and recent grades. Ask the teachers who run those courses to complete their normal tasks on the upgraded copy and record what they find against the test set. Brief them on the navigation and course index changes before the review starts, since those are the most likely to generate questions. Only after that sign-off should the pre-hop snapshot be kept as a fallback and the next hop begin.
What makes a Moodle 3.x to 4.x upgrade longer or more costly
This table lists the factors that change how long a 3.x to 4.x upgrade takes and how much work it creates, along with what to confirm before you ask a vendor for a quote. Read each row against your own site, since the same hop count can mean very different effort depending on plugins, customizations and integrations. Most of the cost comes from the factors that are hardest to see early, so the checks in the right column are worth doing first.
| Driver | Effect on effort | What to confirm |
|---|---|---|
| Number of upgrade hops from your starting version | Each intermediate release needs its own upgrade, test and rollback point, and the hops multiply the testing cycles. Moodle's documented minimum starting versions set the route. | Your exact current Moodle version and the hop sequence the vendor plans, with a test pass after each hop. |
| Count and age of third-party plugins | Every plugin must be checked for a version compatible with 4.x. Plugins that are unmaintained or lack a 4.x release often need replacement or rebuilding. | A plugin inventory with versions, last update dates and a 4.x-compatible replacement or owner for each one. |
| Custom themes and template overrides | Themes built for the 3.x layout and renderer overrides usually need rework for the redesigned navigation and course index, and this work scales with the number of overrides. | Whether the theme is custom, parent-based or core, and the list of overridden templates and renderers. |
| Database size and attachment volume | Larger databases lengthen the upgrade run and the rehearsal copies. Large file stores add time to copying and checking data before and after the move. | Database engine and size, file store size, and whether the vendor will rehearse the upgrade on a full-size copy. |
| Number of integrations (SSO, HR, LTI, video, storage) | Each integration needs its authentication, enrolment or service configuration re-verified against 4.x, and some depend on plugins that also need replacing. | A list of every connected system, its connection method and its owner, plus which ones have a tested 4.x path. |
| PHP and database version jumps | Required PHP and database versions can change across hops, so server upgrades may need to happen in sequence with the Moodle hops. | The PHP and database versions the target release requires, and whether the current servers can run them without a rebuild. |
| Availability of staging and maintenance windows | Without a staging copy that matches production, testing shifts to live users. Limited maintenance windows force slower, smaller steps. | Whether a production-like staging environment exists, how often it refreshes, and the maintenance windows your institution allows. |
| Team availability for testing | Acceptance testing by course designers, administrators and integration owners is often the longest part of the project, and it depends on people who have teaching or other duties. | Named testers for each area, their available hours during the project, and who signs off each hop. |
Questions buyers ask before hiring help for a Moodle 3.x to 4.x upgrade
What drives the cost of a Moodle 3.x to 4.x upgrade?
The size of the plugin set, the number of upgrade steps and the amount of course content that needs checking drive most of the cost. Quoted work usually splits into planning, staging, plugin work, testing, cutover and post-go-live support, and each line should name who is paid for it. Planning covers the upgrade path, server requirements and an inventory of plugins and themes. Staging means building a copy of the live site on the target stack and running each step there. Plugin work covers finding 4.x compatible versions, replacing plugins that have no equivalent and fixing custom code. Testing needs course owners' time. Ask the provider which lines are fixed in price and which are billed on time and materials, and what happens if the inventory turns up more plugins than expected.
Which costs are one-time and which recur after a Moodle upgrade?
Assessment, staging, plugin replacement, testing and cutover are one-time project costs. Recurring costs include hosting capacity for the new stack, maintaining the PHP and database versions the platform requires, applying point releases, updating plugins, running backups and patching the server. Moodle ships major releases in April and October and minor point releases every two months, so the maintenance workload repeats throughout the year. Moodle 4.5 is a long-term support release with security support until 4 October 2027, according to the Moodle releases page. Confirm the support end date of your target release before you budget for ongoing work, and ask who carries the recurring work after go-live.
How long does a Moodle 3.x to 4.x upgrade take?
No single duration applies, because the schedule depends on the number of upgrade steps, the plugin count, the amount of custom code, the volume of course content and the availability of testers. Each step must be completed and tested before the next one starts, so a longer upgrade path adds sequential work. Server rebuilds, database changes and academic calendar constraints also shape the schedule, since cutover is usually limited to a window that avoids term starts and assessment periods. Ask for a written schedule with milestones, dependencies and the decisions that gate each milestone. Be cautious with any provider who quotes a duration before the plugin inventory and the content review are complete.
What does our team need to provide during the upgrade work?
The work needs access to the current server, database, code repository and data directory, plus read access to the plugin list and configuration. A named data owner should approve how user and course data is handled during the move. Course owners and a set of testers must check content and workflows on the staging site, because technical success does not confirm teaching success. A decision maker needs to approve the go or no-go decision, the cutover window and the rollback criteria. Your team should also agree the backup retention period, the maintenance window and who communicates downtime to learners and staff. Missing any of these roles usually shows up later as delay, not as lower cost.
Can our internal team upgrade Moodle without outside help?
Yes, a capable internal team can do the upgrade, provided it has the right skills and time. The team needs Linux and web server administration, PHP configuration, database administration for your chosen engine, and command-line and version control skills. If the site has custom plugins or themes, someone must be able to read and modify PHP and the Moodle plugin APIs. The team also needs people who can run structured testing with course owners. Ask whether anyone has completed a major Moodle upgrade before, and whether the team can keep normal operations running while the project takes priority. If those skills or hours are missing, a fixed-scope engagement can cover the gap, with the work agreed in writing before it starts.
Which PHP and database versions block a Moodle 3.x to 4.x upgrade?
Each intermediate Moodle version sets its own minimum PHP and database versions, so check the release notes for every step on the path rather than assuming the final target sets all requirements. The supplied release notes show how strict these minimums can be: Moodle 5.1 requires 64-bit PHP 8.2 or later and PostgreSQL 15, MySQL 8.4, MariaDB 10.11 or SQL Server 2017 or later, and it requires a site on Moodle 4.2.3 or later. Moodle 5.3 raises those minimums again. Inventory your current PHP and database versions, compare them to each step, and plan the server and database upgrades before the Moodle upgrade begins.
What breaks most often during the move to 4.x?
The most common problems come from plugins without a 4.x version, themes built on older templates, custom code that calls removed or changed APIs, and the redesigned navigation and course index that change how teachers and learners find content. Custom reports, integrations with external systems and scheduled tasks can also fail silently if nobody tests them. Expect that some plugins will need replacing rather than updating. Check each plugin against the release notes for the version you are moving to, and test the navigation with real course owners before cutover so the changes are not discovered by students during term.
What should a written scope for a Moodle upgrade include?
A written scope should name the starting version, the target version and each step between them. It should include an inventory of plugins, themes and custom code, with a decision for each item to keep, replace or remove. The scope should list the PHP and database versions, the environments to be built, the test plan with named testers, the cutover and rollback procedure, and the acceptance criteria. It should state what is excluded, such as content rewrites or new integrations, and what support runs after go-live. DeployOpen engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, so ask any provider to put these items in that document.
How DeployOpen scopes, delivers and supports the upgrade
DeployOpen plans the upgrade from a 3.9 or 3.11 Moodle site in steps, starting with a scope that names each intermediate release, the PHP and database changes it needs, and the plugins that must be replaced or checked. Work is delivered in infrastructure you control, and the engagement is fixed-scope, with the written scope agreed before work starts.
How we scope
- The written scope lists each upgrade hop, its target release and the PHP and database versions each step needs.
- Inventory covers every installed plugin, theme and custom code, with a keep, replace, update or remove decision for each.
- Scope also names the navigation, course index and theme changes that course designers and admins must review.
How we build
- Upgrades run first in a staging copy of the database and moodledata, never on the live site.
- Each intermediate release is installed, tested and recorded before the next step begins.
- Web server configuration is checked at each hop, including any document root change that a target release requires.
How we hand over
- Handover includes an as-built record of versions, PHP and database settings, plugin decisions and configuration changes.
- Test scripts for course access, quizzes, grading and sign-in are run and the results are documented for your team.
- Administrators and course designers receive a short guide to the navigation and course index changes.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after the handover.
- Later Moodle releases, including minor point releases, can be planned into a retainer or a new fixed-scope project.
- Before any later upgrade, we confirm the minimum starting version and the PHP and database versions the target requires.
