Upgrading ERP software can feel risky, especially if you’re not confident in the process yet. This guide walks through updating ERPNext to the latest version safely and methodically, whether you’re moving between minor releases or doing a major jump like ERPNext v14 to v15.

By the end, you’ll know every step from preparation to post-upgrade verification, how to recover from the most common failures, and how to keep future upgrades painless.

Table of Contents

• Why You Should Keep ERPNext Updated
• Prerequisites Before You Begin
• Step-by-Step Upgrade Instructions
• Common Errors and How to Fix Them
• Post-Upgrade Checklist
• Future-Proofing Your ERPNext Installation
• Frequently Asked Questions
• Conclusion

Why You Should Keep ERPNext Updated

Running an old ERP version is a lot like driving on worn brakes — it works, right up until it doesn’t. Most of the ERPNext errors we see in support requests trace back to instances that went too long between updates, not to the software itself.

Staying current gets you better performance, fewer crashes, and an ERPNext install that actually matches what your business needs today. Newer releases are also simply faster and lighter than the versions they replace.

Security Enhancements & Bug Fixes

Every release ships fixes for known vulnerabilities and bugs discovered since the last one. Skipping updates means carrying those weaknesses forward indefinitely.

Access to New Features & Improvements

Recent ERPNext releases bring better dashboards, faster reports, and smoother workflows across finance, HR, inventory, and e-commerce.

Long-Term Support (LTS) Considerations

Sticking to supported versions (like the current v14/v15 line) keeps you eligible for ongoing patches and community support for longer, instead of being stuck on a version nobody is patching anymore.

Performance and Compatibility Benefits

Modern ERPNext releases are faster, integrate more easily with third-party tools, and work with current Node.js LTS versions. They run fine on Ubuntu 22.04 or 24.04 — upgrading ERPNext does not require upgrading your OS unless your current Ubuntu version is genuinely out of support.

Prerequisites Before You Begin

Jumping into an upgrade without preparation is how systems end up down overnight. A few minutes of prep here saves hours of troubleshooting later.

Backup Your ERPNext Instance

Always take a full backup before you start:

$ bench --site [your-site-name] backup --with-files

Store the backup somewhere off-site, not just on the same server.

Check for Custom Apps or Scripts

List what’s installed on the bench:

$ bench list-apps

Any custom apps are the most likely thing to break during an upgrade — note them now so you know what to check afterward.

Review Official ERPNext Release Notes

Check the ERPNext release notes for the version you’re moving to, so you know about breaking changes or deprecations before you hit them.

Check System Requirements

Confirm Python, Redis, and MariaDB meet the target version’s requirements, and that Node.js is at least version 18 — see Step 2 below for how to update it with nvm.

Optional: Use a Staging Environment for Testing

If you can, clone your site to a staging bench and run the upgrade there first. Catching a broken custom app on staging costs you nothing; catching it in production costs you downtime.

Step-by-Step Upgrade Instructions

This section uses real terminal commands for the actual upgrade and ERPNext database migration. Follow them in order.

Step 1: Locate Your Frappe Bench Directory

$ cd /path/to/your/frappe-bench

Everything below runs from inside this directory.

Step 2: Update Node.js (If Required)

If you’re not already on Node 18 or newer:

$ nvm install 18

$ nvm alias default 18

$ source ~/.bashrc

Skipping this is the single most common cause of a build failing partway through an upgrade.

Step 3: Pull the Latest Code

For a minor-version update (staying on the same major branch):

$ bench update --reset

For a major upgrade, such as moving to v15:

$ bench switch-to-branch version-15 frappe erpnext --upgrade

Step 4: Run Migrations

$ bench --site [your-site-name] migrate

This applies the schema changes the new version needs.

Step 5: Restart Supervisor & Background Jobs

$ sudo supervisorctl restart all

This restarts the web workers and background queues so they pick up the new code.

Step 6: Verify the Upgrade

$ bench version

Then open your site in the browser: confirm pages load, reports run, and there are no “module not found” errors in the console.

Common Errors and How to Fix Them

Module Not Found Errors

Usually means a dependency didn’t install cleanly. Re-run the install for the affected app:

$ bench get-app [app-name] --branch version-15 --resolve-deps

Migration Fails Partway Through

Migrations are safe to re-run — just run Step 4 again:

$ bench --site [your-site-name] migrate

If a specific patch keeps failing and you’ve confirmed it’s safe to skip (check the error against the release notes first):

$ bench --site [your-site-name] migrate --skip-failing

Custom App Conflicts

Check each custom app’s compatibility with the new version before upgrading. If one isn’t ready yet, remove it from the site rather than let it break the migration:

$ bench --site [your-site-name] uninstall-app [app-name]

Cache and Build Issues

If the UI loads with missing styles or broken JavaScript after the upgrade:

$ bench build

$ bench clear-cache

Post-Upgrade Checklist

An upgrade isn’t done the moment the commands finish — a few minutes of checking now catches problems before your team does.

Test Critical Workflows

Open the ERPNext desk and walk through the workflows that actually matter to your business: create a sales order, raise an invoice, run payroll, confirm email notifications still fire.

Reinstall or Update Custom Apps

For each custom app, pull the latest compatible version from its repo, run migrations again, and test its core functionality directly.

Review Logs for Warnings

Check frappe.log and bench.log in the bench’s logs/ directory for anything that looks like a missing method or a broken setting reference.

Notify Your Team

Let users know what changed, especially anything in the UI that moved or behaves differently — it heads off a wave of “is this broken?” messages.

Future-Proofing Your ERPNext Installation

Staying current is easier the second time if you build a few habits in now.

Use Version Control for Customizations

Track your Client Scripts, custom fields, and config changes in Git. It makes it obvious what’s yours versus what came from the framework, and nothing gets silently overwritten during an upgrade.

Set Up a Staging Environment

Keep a staging bench around permanently, not just for this one upgrade — it pays for itself the next time too.

Schedule Regular Backups and Updates

Automate nightly backups with cron, and put upgrades on a recurring schedule (monthly or quarterly) instead of waiting until something forces your hand.

Watch ERPNext’s Release Activity

Keep an eye on the Frappe/ERPNext GitHub releases so new versions don’t catch you off guard.

Frequently Asked Questions (FAQs)

Do I have to update Ubuntu after upgrading ERPNext?

No. ERPNext v15 runs fine on Ubuntu 22.04 or 24.04. You only need to touch your OS version if it’s genuinely past end-of-life.

Which Node.js version does ERPNext v15 need?

Node.js 18 or later. Use nvm install 18 and nvm alias default 18 as shown in Step 2.

Can I roll back if the upgrade goes wrong?

Restore from the backup you took in the prerequisites step. This is exactly why that backup isn’t optional.

What if I have custom apps installed?

Check each one’s compatibility with the target version first. Disable or temporarily uninstall anything that isn’t ready, upgrade, then reinstall and test it.

Is there a GUI for upgrading ERPNext?

No — upgrades run through the bench command line, using bench switch-to-branch or bench update as covered above.

Conclusion

That’s the full process for updating ERPNext: back up first, update Node if needed, pull the new code, migrate, restart, and verify. Following it in order is what keeps an upgrade boring instead of stressful.

Regular updates mean better performance, tighter security, and access to features you’re currently missing out on. If you’d rather not run this yourself, get in touch — we handle ERPNext upgrades directly.