Applying ERPNext minor updates with bench update

What changes between minor releases and what each change asks of you

This table compares the categories of change that a bench update carries into a site, the impact of each one, and the action the team should take. Read the release notes for each tag before applying it, because the categories below describe how bench update works, not what a specific release changes. The main takeaway is that code, dependencies, patches and restarts each need their own check before production.

What bench update does when you run it without flags

When to update everything and when to exclude an app

Backups, customization inventory and a test site before production

A minor update is small in version terms but still runs migrations against your data, so the work before it matters as much as the command. The cards below cover what to protect, what to inventory, and where to rehearse. Each one is a check you can run on your own site before the update window opens.

The minor update sequence on a production bench

This sequence moves a version 15 or 16 ERPNext site to the latest minor release with a verified backup, a tested rehearsal on a test site, and a defined rollback point, so production changes are predictable and reversible.

1. Confirm the target release and read its notes

   Identify the minor release you plan to apply for each supported major version and read its release notes for patches, changed behavior and any companion apps that need matching versions. Confirm that your major version is still within its support window using the Frappe supported versions page. Done means you have a written target version for each app on the bench and a list of any apps that must be excluded from the update, with the reason for each.

2. Take and verify a backup

   Create a full backup of the production site, including the database and the files directory, before anything changes. Copy the backup off the bench host to storage that survives a failure of that host. Verify the backup by confirming the archive files exist, are not zero bytes, and that the expected site name and timestamp appear in the file names. Where your team can do it safely, restore the backup to a separate machine to prove it works. The output is a backup you can name, locate and restore.

3. Define the rollback point before changing anything

   Record the backup identifier, the current app commit or version for each app, and the bench and Python environment details in the change record. This is the rollback point: if the update fails, the plan is to restore the database and files from this backup and return the apps to these recorded versions. Agree with the business owner who has the authority to choose rollback, and what they need to see before choosing it. Done means the rollback steps are written down and someone other than the operator has reviewed them.

4. Apply the update to the test site first

   Clone or restore production data to a test site on the same major version and the same app set, then run the planned bench update there using the same exclusions and flags you intend to use in production. Record every warning, patch output and error. Done means the test site completes the update without failed patches and the site loads in the browser after the restart.

5. Run functional checks on key documents and reports

   On the updated test site, check the workflows your organization depends on: create, submit and cancel a sales invoice, purchase invoice, payment entry, stock entry and work order where you use them, and open the general ledger, trial balance and stock balance reports. Compare totals and outputs with the pre-update production values for the same filters. Check that print formats render and that any custom scripts or integrations still fire. Done means each check has a recorded pass or a logged defect with an owner.

6. Schedule the window and communicate the rollback decision

   Choose a maintenance window when users are not posting transactions and the scheduler can be paused. Tell users when the site will be unavailable, and tell the approver what the rollback criteria are, such as failed patches, failed functional checks or errors in the logs. Confirm that the backup from earlier is still current or take a fresh one immediately before the window opens. Done means the window, the contacts and the rollback criteria are written in the change record and acknowledged.

7. Run bench update on production with excluded apps

   Put the site in maintenance mode if your procedure requires it, then run bench update from the bench directory. Use exclude-app for any companion app you must hold at its current version, and confirm the exclusion does not leave a dependency mismatch. Watch the output for patch errors. Done means the command finishes without failures and the bench restarts. If a patch fails or the output shows errors you cannot resolve within the agreed window, stop and execute the rollback to the recorded backup.

8. Verify logs, scheduler and key transactions

   After the restart, check the web and worker logs for new errors, confirm the scheduler is running and background jobs are being processed, and repeat a short set of the functional checks from the test site on production. Confirm that scheduled jobs such as email queue and recurring documents run without errors. Close the change only when the logs are clean for the agreed observation period, the scheduler is active, and the business owner has signed off the rollback point as no longer needed.

What makes a minor update take longer

This table lists the factors that change how long a bench update takes to test and apply, and what each one asks of the team. Read each row as a question to put to a partner: the more of these conditions apply to your site, the more testing and checking the update will need before it reaches production.

Questions teams ask before applying ERPNext minor updates