ERPNext Upgrade Guide: Moving Between Major Versions Safely

ERPNext releases a new major version roughly every year or two, with regular minor updates in between. Minor updates are usually routine. Major upgrades change data structures, move features between apps and can break custom code, so they deserve a proper plan.

1. Inventory what you have

Before anything else, list:

• Every installed app: ERPNext, Frappe HR, India Compliance, Payments, third-party and custom apps
• Custom fields, property setters and custom print formats
• Client and server scripts
• Integrations and the API calls they make
• Reports and dashboards that users rely on

Remove what nobody uses. Every unused script or app is one more thing to test.

2. Check what moved

Major ERPNext versions have moved features out of ERPNext into separate apps. HR and payroll moved into Frappe HR; Indian regional features moved into India Compliance; other areas such as the webshop, lending and some integrations have also moved into their own apps over time.

If you are upgrading across one of those changes, the separate app must be installed as part of the upgrade, and anything that referenced the old location — scripts, print formats, reports, integrations — must be checked.

3. Check every app supports the target version

• Frappe's own apps have branches per version.
• Third-party apps may lag behind; check before committing to a date.
• Your custom apps need testing and, often, changes for framework API updates.

4. Upgrade a copy on staging

Restore a recent production backup to a staging bench and run the upgrade there:

1. Switch apps to the target version branches
2. Run the database migration and watch for failed patches
3. Rebuild assets and restart services
4. Fix custom app errors, then repeat on a fresh copy until it runs cleanly

If you are several versions behind, step through each intermediate version and test at each step.

5. Test functionally

Key users run their real processes on the upgraded staging site: quote to cash, procure to pay, manufacturing, payroll, month-end close and GST reports where relevant. Pay special attention to:

• Custom print formats, which often break on template changes
• Scripts referencing renamed fields or functions
• Permissions and role changes
• Integrations

6. Plan the production upgrade

Write a runbook with timings from your rehearsal: backup, maintenance mode, upgrade, smoke tests, go/no-go and rollback steps. Schedule it outside business hours, with key users ready to check their processes before the system reopens.

7. Afterwards

Monitor errors and background jobs closely for the first days, and keep the pre-upgrade backup until you are confident. Then plan the next one: staying current is far cheaper than catching up.

Making upgrades easier next time

• Keep all customisations in a custom app with fixtures, in Git
• Prefer configuration to scripts, and scripts to core changes — and never change core code
• Apply minor updates on a regular schedule
• Keep a staging site that mirrors production

Need help?

Our ERPNext migration and upgrade service handles stuck and multi-version upgrades, including custom app fixes and the move to Frappe HR or India Compliance. For the same exercise on Odoo, see our Odoo upgrade guide.