ERPNext companion apps upgrade services

Upgrading ERPNext companion apps starts with one matching branch per hop

If your site runs ERPNext alongside apps split out from it, such as Frappe HR, Lending, Payments, India Compliance or Ecommerce Integrations, each of those apps must be on the branch that matches the target ERPNext version before bench migrate runs. The path is one major version at a time, so each hop needs its own matching set of branches, tested in order. Start by listing every installed app with bench version on the current site, then record which app versions and branches you have today. Support windows set the urgency: according to Frappe's supported versions page, ERPNext and Frappe Framework version 14 reached end of life on January 31, 2026, version 15 is planned to be supported until the end of 2027, and version 16 until the end of 2029. Confirm the exact app list and branch names for your own version pair in the release notes and repository of each app, because which apps split out changes between major versions.

Treat the companion app list as a checklist you verify, not one you assume. Compare the apps in apps.txt and the installed-apps list with the apps the target version expects, and note any app you run that has no matching branch for the target. Frappe HR and India Compliance, for example, are typically tied to specific ERPNext majors, so a mismatch can stop the migration partway through. Decide early whether an unmaintained or third-party app will be replaced, moved to a supported equivalent or retired, because that decision affects the test plan and the sign-off. Also check that the Frappe Framework version your site runs matches the one the target branch requires. The supported versions page is the starting point for that check.

Work on a copy of production first. Clone the site, check out each companion app at its matching branch in the bench, run bench get-app or bench update as your process requires, and confirm bench migrate completes on the copy before anything changes in production. Keep the backup from before each hop so you can restore to the previous major if a migration fails. Repeat the sequence for each major version between your current release and the target, rather than jumping straight to the newest version, since each hop can change the apps and their branches. Record the exact commit each app is on at every step so the production run repeats what the test run proved.

What changes between versions that affects companion apps

This table lists the version changes in the supplied facts that affect companion apps during an upgrade, with the impact on each app and the action to take. Read each row before planning the migration order, because a companion app that is out of step with ERPNext can block the migrate step. Confirm every app's split version and branch name against the official repositories before you rely on them.

Change	Impact on companion apps	Action needed
Version 14 end of life on January 31, 2026	Sites still on version 14 no longer receive Frappe support updates, and companion apps on that line follow the same window	Confirm your target version and list every installed companion app before you start the upgrade
Version 15 support planned until end of 2027	Companion apps on version 15 branches have a supported window that matches the core release	Check the support-versions page and plan the companion app branch for each hop
Version 16 support planned until end of 2029	Companion apps must have a matching version 16 branch before you migrate to version 16	Confirm the version 16 branch exists for each app you use, and do not assume it does
Frequent minor releases (v15.123.0 on October 14, 2026 and v16.51.1 on October 15, 2026)	Companion apps are updated alongside core minor releases, so a pinned app can drift out of step	Keep core and each companion app on matching branches and test updates on a copy of the site first
Server Scripts disabled by default from version 15	Custom server logic in companion app customizations stops running until the setting is enabled	Set server_script_enabled deliberately, and review scripts used by companion app workflows after upgrade
Frappe Cloud support plan for warranty coverage	Warranty coverage from Frappe requires a listed version and a matching Frappe Cloud support plan	Ask Frappe whether your hosting and plan meet the requirement before committing to a target version
App split from ERPNext (for example Frappe HR, Lending, Payments, India Compliance, Ecommerce Integrations)	Apps split out in a given major version must be installed separately, and the version at which each split took effect should be confirmed	Confirm each app's split version against the official repository before deciding which apps to install
Branch naming for companion apps	Branch names must match the core version; a mismatched name installs the wrong code line	Confirm each app's branch name in its official repository and pin it in your bench or image configuration

Why a companion app on the wrong branch blocks bench migrate

A companion app on the wrong branch stops bench migrate because it is code that runs against the core's DocTypes, hooks and patches, and those interfaces change between major versions. Frappe HR, Lending, Payments, India Compliance and Ecommerce Integrations each register their own DocTypes, extend core documents through hooks.py, and ship patches that expect specific fields and tables to exist in a specific shape. When the app branch belongs to a different major version than the core, the migrate step can run a patch against a schema the core has already changed, or skip a change the app depends on. The failure is often not a clean stop. Records can be half-converted, with some rows updated and others left in the old format, and the core will not know how to read them.

Before you run migrate, confirm that every installed app is on the branch that matches your target ERPNext version, and that bench reports the same major version for each app. Check apps.txt in the bench directory and the branch of each app's git checkout, and record the result alongside your backup. Confirm the matching branch for each companion app in its own repository and in the upgrade notes for your target version, since the pairing is not something to assume from the names alone. If an app is missing from the target, decide whether it is still needed before you install it, because a stale app left in place will still be migrated.

Recovering after a bad migrate is far more expensive than checking first. You may need to restore the database and files from the backup taken before the upgrade, reinstall the correct branches, and rerun the migration on a test copy to find the cause. That work consumes the maintenance window, so the people who would have signed off the upgrade lose time they had planned for testing. A version check takes minutes and needs no downtime. Treat a mismatch as a stop condition in your runbook, not a warning to note and proceed past.

What to back up and inventory before touching any app

Companion apps move in step with ERPNext, so a failed upgrade is hard to unwind if the starting point is unclear. The cards below cover what to record and copy before any app changes, and each one gives the team a way to return to a known state.

Inventory apps and their branches

List every app installed on each bench, including Frappe HR, India Compliance, Lending, Payments and Ecommerce Integrations, with the exact git branch or tag and the commit it is on. Run bench version and compare it with the apps.txt file so nothing installed by hand is missed. Record which apps each site actually uses, because an app installed on the bench but not on a site still has to match the target branch. Confirm the target branch for every app before work starts.

Full database and file backup per site

Take a complete database dump and a copy of each site's private and public files folders before the upgrade, and keep them off the server being changed. Store the backup with its matching app commits, since a restore onto different code can fail. Test that the backup restores on a separate machine. Ask whoever runs the backups which copy is the last known good one and how long it takes to restore.

Customizations and their owners

Inventory custom fields, client and server scripts, print formats, reports, workflows and custom apps, and name one owner for each. Companion app upgrades often change the doctypes these customizations attach to, so the owner must check their item after each migrate. Export customizations as fixtures or files where possible so they live in version control. Flag anything without an owner before the upgrade starts.

Test site from a recent production backup

Restore a recent production backup to a separate site on a separate bench, with the same app branches as the target. Run bench migrate there first and read the output for errors from each companion app. Walk through the workflows that finance, HR and sales use every day, and compare results with production. Keep the test site until production is confirmed working, because it is the only safe place to repeat a failed step.

Server Scripts setting

If the site uses Server Scripts, check the server_script_enabled setting before upgrading to version 15 or later, because scripts are disabled by default from that version. Record which scripts exist, which document events or API endpoints they serve, and whether an integration depends on them. Public shared benches on Frappe Cloud do not allow Server Scripts, so a script that runs on another host will not carry over. Test each script on the test site after enabling the setting.

Frappe Cloud support plan status

If the site is hosted on Frappe Cloud, confirm that the support plan matches the version being upgraded to before scheduling work. Frappe's supported versions policy ties warranty coverage to a listed version and a matching support plan, so a lapsed or mismatched plan can leave the upgrade without vendor coverage. Ask Frappe Cloud support to confirm the plan in writing and note the date. Sites outside Frappe Cloud should record their own support arrangement instead.

Installing matching app branches on bench, Docker or Kubernetes

On a bench installation, each app is a Git checkout inside the bench's apps directory, so the branch is set when the app is fetched or switched. ERPNext and its companion apps are installed with the bench command line tool, so every app on a site must come from the same release line as the core.

Set the branch at fetch time: Run bench get-app with --branch set to the release line that matches the target ERPNext version for ERPNext, Frappe HR, India Compliance and any other companion app you run.
Switch existing checkouts: For apps already in the apps folder, check out the matching branch in each repository with Git, then confirm the active branch in each folder.
Install before migrate: Install each new app on the site with bench --site <site> install-app, and only then run bench --site <site> migrate.
Keep one release line: Do not mix a branch of Frappe with an app from another release line. Move the core and every companion app in the same planned pass.

After the migrate finishes, check the installed app list on each site, confirm the versions with bench version, and review the migrate output for errors on a test copy before you touch production.

The frappe_docker repository builds images and provides Compose files for ERPNext and other Frappe apps. In this model the branch choice happens at build time, because the app code is baked into the image. A running container is not the place to change app versions, so the upgrade starts with a new image.

Declare the app set at build: Name ERPNext and each companion app with the branch for the target release in the build inputs that the repository documents. Confirm the current mechanism in its build documentation before you start.
Build a new image: Build a fresh image with a tag that identifies the target release, and keep the previous image so you can roll back.
Point every service at the new image: Update the Compose file so the backend, workers, scheduler and Socket.io services all run the same image tag.
Run migrate once per site: After the new containers start, run the migrate step, either bench migrate or the migrator service defined in the Compose file, before users return to the site.

The sibling page on upgrading ERPNext on Docker with frappe_docker covers the sequence in detail. Before you open traffic, check that every service reports the same image tag, that the app list inside the image matches your plan, and that each site shows the expected app versions.

The upgrade sequence, from app inventory to a verified site

The sequence turns a set of ERPNext and companion app versions into one matched, tested app set on a production site, with a rollback point at every migrate. Each step has a named output that gates the next.

Confirm the supported path and target version
Check the Frappe supported versions page to confirm your current ERPNext and Frappe version is listed, and choose the target major version before touching any app. Version 14 reached end of life on January 31, 2026, so a v14 site needs a decision between version 15 and version 16 first. Confirm with Frappe whether your support plan covers the target, since warranty coverage depends on a listed version and a matching Frappe Cloud support plan. The output is a written target version for ERPNext, Frappe and each companion app.
Inventory apps and branches on the live site
Run bench list-apps on the production bench and record every app with its installed branch and commit. Include Frappe HR, Lending, Payments, E-commerce Integrations and India Compliance if present, along with any custom apps. Map each companion app to the branch that matches the target version, and flag any app that has no matching branch or that the vendor no longer maintains. The output is a versioned app manifest that names the exact branch for every app.
Take and verify a full backup
Create a full site backup with bench backup --with-files, then copy the database dump, private and public files, and the apps directory state off the server. Record the backup file names, sizes and checksums in the change record, and restore the backup to a scratch location to confirm it is readable. This backup is the only rollback path, because a failed migrate cannot be reversed by reinstalling an older app version alone. The output is a restore-tested backup linked to the app manifest.
Build a test environment with the same app set
Create a test bench or container image that uses the same ERPNext, Frappe and companion app branches recorded in the manifest, and restore the production backup into a separate test site. Keep the test site's app list identical to production, including custom apps, so that migrate results apply to the real site. Use a separate test site and never point test tooling at production. The output is a test site whose bench list-apps output matches the production manifest line for line.
Install each companion app on its matching branch
On the test bench, fetch each companion app with bench get-app using its matching branch, then install it on the test site with bench --site install-app. Install in dependency order, starting with Frappe HR and India Compliance when they are required, and install Lending, Payments or E-commerce Integrations only if the site uses them. Record each app's commit after install, because later bench update runs can move it. The output is a test site where every app installs without error and bench list-apps matches the target manifest.
Run migrate on the test site and take a checkpoint backup
Run bench --site migrate on the test site, then review the migrate log for patch failures and warnings before you continue. Take a new backup immediately after a successful migrate, label it with the target version, and keep it with the pre-migrate backup. This checkpoint is the rollback point for the next stage, and it only works if the pre-migrate backup from the preparation step is still available. The output is a clean migrate log and a labeled post-migrate backup.
Verify records, reports and customizations
Compare record counts and key balances between the source backup and the migrated test site, covering ledgers, stock, payroll and any app-specific documents. Open the print formats, custom reports, scripts and custom fields your business depends on and confirm they behave as before. Log each mismatch with its DocType and owner, and resolve it before production. The output is a signed verification checklist showing that every critical record class matches or has an accepted explanation.
Repeat the sequence on production in a maintenance window
Once the test site passes verification, schedule a maintenance window, put the production site into maintenance mode, and repeat the install and migrate steps using the same app branches recorded in the manifest. Take the checkpoint backup at each migrate, and keep the pre-upgrade backup until post-cutover checks pass. If production diverges from the test results, stop and restore from the pre-migrate backup rather than patching live data by hand. The output is a production site on the target version with the same app list as the verified test site.

Testing and rollback checkpoints for each app

Each companion app fails in a different place, so each needs its own test set run on a copy of production before cutover. The cards below list what to exercise per app, then the rollback path that applies if a check fails. Confirm the exact test cases against each app's own documentation, because the release notes for each app change between versions.

Frappe HR payroll and attendance

Run a full payroll cycle and an attendance sync on the test site, comparing salary slips, leave balances and shift assignments against the same period in production. Check that attendance device imports and holiday lists still map to the right employees after the upgrade. Pay particular attention to salary structures and components, since a changed field or formula can alter net pay without raising an error. Record each difference before go-live, and do not sign off until the payroll owner has reviewed the sample slips.

India Compliance tax and e-invoice flows

Test GSTIN validation, tax category mapping and invoice creation for a sample of sales and purchase documents, then confirm that e-invoice generation and e-way bill requests still behave as before. Check that HSN code and tax template rules applied to the test documents match the figures your tax advisor expects. Because tax errors often reach filed returns before anyone notices, treat any mismatch as a stop condition and not a warning.

Payments and reconciliation checks

Process a set of test payment entries through each configured gateway, then run bank reconciliation against a matching bank statement file. Confirm that payment request status, references and exchange differences post to the same accounts as before, and that refunds and partial payments still close the right invoices. Keep a list of open payment requests from production so that you can verify none were duplicated or left unlinked after the migration.

Lending loan schedule validation

Compare repayment schedules, interest accruals and penalty calculations for a representative set of loans against schedules produced before the upgrade. Run the daily accrual and a disbursement on the test site to confirm the scheduler posts the expected journal entries. Any schedule that moves by even one installment should be traced to its cause, because loan balances feed directly into provisioning and customer statements.

Ecommerce Integrations order sync

Replay a batch of recent marketplace or storefront orders against the test site and confirm that customers, items, taxes and fulfillment status map as they do in production. Check the sync queue for failed jobs and confirm that no order is imported twice when the integration is re-enabled. Confirm the connector's current supported versions and any credential changes with its documentation before you point it at the upgraded site.

Rollback and business sign-off

Before cutover, take a full database and files backup of production and confirm you can restore it to a scratch server, then rehearse the restore on the test site. Treat a successful dry run of the complete upgrade on the test site as the entry requirement for production. Each business owner for payroll, tax, finance, lending and sales should sign the test results in writing, and that sign-off, together with the restore record, is the basis for any rollback decision.

What makes a companion app upgrade take longer

This table lists the factors that stretch a companion app upgrade and the mitigation for each. Read it before you scope the work, because each row changes how many apps, tests and data checks the migration has to cover. The main takeaway is that the count of apps matters less than how much custom code and data sit on top of them.

Driver	Why it adds effort	How to keep it down
Number of installed companion apps	Each app split from ERPNext needs a matching branch, its own dependency install and its own migrate step, so the sequence grows with every app added.	Remove apps you no longer use before the upgrade and confirm the exact list of apps per site in your bench or image.
Custom code touching companion DocTypes	Server scripts, custom apps and hooks that read or write Payroll, Lending, Payment or India Compliance DocTypes can break when fields or methods change between versions.	Inventory every script and hook that references those DocTypes, then retest each one on a staging copy at every version hop.
Data volume in affected tables	Large attendance, salary slip, loan or GST tables take longer to migrate and to verify, and failed migrations on big tables are harder to roll back.	Confirm backup and restore timing on a copy of production, and check record counts before and after each migrate step.
Number of sites on one bench	Every site on a bench runs its own migrate, so one bench with several sites multiplies the time and the number of places where a failure can stop the run.	Upgrade one representative site first, then the rest in a fixed order, and record which sites have finished each step.
Integrations that depend on app data	Payment gateways, bank feeds, ecommerce connectors and payroll exports read fields from companion apps, so a field rename can silently stop a sync.	List each integration with the DocTypes it reads and writes, and test a full round trip against the upgraded test site.
Frappe Cloud support plan status	Frappe's supported versions policy ties warranty coverage to a listed version and a matching Frappe Cloud support plan, so a lapsed plan can add a support question to the upgrade.	Confirm with Frappe that your plan covers the target version before the change window opens.

Questions buyers ask before upgrading companion apps

What does it cost to upgrade companion apps alongside ERPNext?

The cost depends on the scope agreed in writing, not on a published rate. DeployOpen does not publish a price list, and a quote follows from the written scope. The main cost components are the inventory and version check, the matching branch installs on a test site, the migration runs and fixes for each app, retesting of your customizations, and the cutover. Costs rise with the number of companion apps, the amount of custom code that touches their doctypes, and the number of sites. The one-time work is the upgrade itself. Ask any quote to separate one-time migration work from any recurring retainer for minor updates and support, and to name the apps and sites in scope.

How long does a companion app upgrade take?

The timeline is set by how many apps you run, how far your data and customizations diverge from the defaults, and how many test cycles your business needs before sign-off. No duration is given here because no researched figure is available for this work. Before you commit to dates, confirm with the vendor which branch each app uses for your target version, and check the release cadence on the frappe/erpnext releases page, since both supported major versions receive frequent minor releases during your project. A written scope should show the planned test cycles and the cutover window.

What must our team provide before a companion app upgrade starts?

You need to provide four things before work begins: a complete app inventory, verified backups, representative test data, and named business sign-off. The inventory should list every installed app, its current branch, any custom app and any app you have modified. Backups must be tested with a restore to a separate environment, not just taken. Test data should include real transaction types for accounting, stock and payroll, anonymized where required. Business sign-off means named owners in finance, operations and HR who will approve each test cycle and the go-live decision. Missing any of these usually extends the timeline and increases cost.

Can an internal team upgrade companion apps without a partner?

An internal team can do it if it has Frappe bench experience, a staging environment that mirrors production, and time to test each step. The skill gaps usually sit in reading breaking-change notes across several apps, debugging failed migrations, and retesting custom scripts and print formats. Server Scripts are disabled by default from version 15 and must be enabled with server_script_enabled, so check any custom logic that depends on them. Compare the cost of your own team's time, including the risk of a failed cutover, against a fixed-scope engagement. DeployOpen plans, implements and documents this work in your infrastructure, and the written scope defines what it covers.

Can India Compliance or Frappe HR be upgraded before ERPNext core?

Do not upgrade a companion app ahead of the core unless its matching branch for the target core version is confirmed. Each app is built against a specific ERPNext version, so an app on a newer branch can fail against an older core. The safe order is to check the compatibility of each app with your target version, install the matching branches on a test site, and then run the core migration with the apps in step. India Compliance changes GST handling, so verify tax templates, e-invoicing settings and reports against your test data before go-live. Confirm the exact compatible versions with the app maintainers before you plan the sequence.

What happens if a companion app has no branch for our target version?

You have three options, and the choice should be made before the upgrade starts. You can stay on a core version where the app has a matching branch, which may conflict with your end-of-life plans, since version 14 reached end of life on January 31, 2026. You can replace the app's functions with a supported alternative, which needs data mapping and retesting. Or you can fork or maintain the app yourself, which adds ongoing ownership of patches and security fixes. Frappe's supported versions policy also ties warranty coverage to a listed version and a matching Frappe Cloud support plan, so check that position with Frappe before you decide. Document the decision in the scope.

How do we confirm the upgraded apps still work after cutover?

Verify each app with a written test plan that covers its core business flows, not only whether the site loads. For Frappe HR, that means a payroll run, leave and attendance checks. For Lending or Payments, it means a test loan or payment through the full cycle. For India Compliance, it means generating and reconciling GST returns and invoices against known results. Keep the test results as evidence for your change record. Plan a rollback path from the verified backup, and agree the criteria for using it before cutover begins. Your auditors may ask for this evidence, but a test plan does not replace their independent assessment.

How DeployOpen scopes and delivers a companion app upgrade

DeployOpen plans, implements and documents self-hosted ERPNext upgrades inside your own infrastructure, including the companion apps that split from ERPNext. We agree the app list, matching branches and test plan in writing before work starts, so Frappe HR, India Compliance and the other apps move in step with the core upgrade.

How we scope

Inventory every installed app, its current version and the branch that matches your target ERPNext release.
Confirm which companion apps you run, such as Frappe HR, Lending, Payments, India Compliance or Ecommerce Integrations, and which you need to add.
Agree the written scope, deliverables and timeline before work starts, since most engagements are fixed-scope.
Ask the quote to list rehearsal runs, customization retests and the rollback plan as separate line items.

How we build

Clone a staging copy of production, then install matching companion app branches before running the migration.
Run bench migrate on the staging copy and record every patch, error and warning for review against the scope.
Retest custom fields, scripts, print formats, reports and integrations that depend on companion app doctypes.
Repeat the rehearsal until the staging run completes cleanly, then agree the production cutover window with you.

How we hand over

Deliver a written record of app versions, branch names, configuration changes and patches applied in each step.
Document the rollback procedure, including the database backup and the exact app versions to restore if needed.
Provide test results and open items so your team can judge readiness before sign-off.
Walk your administrators through the post-upgrade checks they need to repeat after future minor releases.

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after the engagement closes.
Keep companion apps on matching branches as ERPNext receives frequent minor releases on supported versions.
Review new companion app releases with you and plan their testing before they reach production.
Confirm with your team which support plan, hosting arrangement and maintenance window apply to your sites.

Upgrading Frappe HR, India Compliance and other companion apps with ERPNext