Upgrading ERPNext from version 13 or older: why it is a staged project
A self-hosted ERPNext site on version 13 or earlier has usually fallen out of support, and it carries customizations written against older APIs. The upgrade must run one major version at a time, with checks between each hop, and the path must end on a version that is still supported. 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 those dates against Frappe's supported versions page before you fix the target, because they are the basis for the rest of the plan.
The team chooses the final target, and that choice shapes everything else. Landing on version 15 gives a shorter support window and a smaller set of changes to absorb in one go. Landing on version 16 adds the newest breaking changes, including the requirements for custom apps and the removal of some whitelisted methods, but it gives the longest runway. Each intermediate hop also carries its own app splits, so the number of hops, the order of apps and the test cycles should be agreed in writing before any production work starts.
The path is not a single jump, because each major release changes the database schema, the app boundaries and the behavior of documents and reports. A migration that passes on one hop can still leave stock valuations, ledger balances or print formats wrong for the next. Plan a restore point and a test site before each hop, run the same reconciliation checks after each one, and retest every custom script and app before moving on. Ask any partner to show the checks and the rollback step for each hop in the written scope, not only the final cutover.
Which changes hit a v13 site on each hop
This table compares the version-specific changes that affect a v13 site as it moves forward, with the impact and the action each one requires. Read each row against the hop it applies to, and treat the release notes for every intermediate version as the final check for breaking changes not listed here.
| Change | Impact on the site | Action needed |
|---|---|---|
| v14 split of Frappe HR | HR doctypes, workflows and reports no longer ship inside ERPNext, so a v13 site with HR data can fail or lose functionality after migrating. | Confirm which HR features are in use, install the matching Frappe HR branch before running migrate, and test payroll and leave records on a copy. |
| v14 split of companion apps | Other apps moved out of the core in v14, such as those covering Lending, Payments and e-commerce integrations, must be present on the bench before the upgrade runs. | List every installed app and its source, then match each app to a branch that supports the target version before the migration step. |
| India Compliance for Indian GST sites | GST configuration and features can break when the site moves forward without the India Compliance app matched to the Frappe version. | Follow the India Compliance migration guide for sites coming from v13, and confirm the installation guide's Frappe version requirement before upgrading. |
| Server Scripts disabled by default in v15 | Any Server Script on a v13 or v14 site stops running after the move to v15 unless it is explicitly enabled. | Inventory all Server Scripts, enable server_script_enabled only where the business case is confirmed, and test each document event and API endpoint. |
| Frappe Cloud public shared benches | Server Scripts are not allowed on public shared benches, so logic that relies on them cannot run there. | If scripts are required, plan for a bench or self-hosted environment that permits them, or move the logic into a custom app. |
| Remaining breaking changes per version | Each intermediate release can add breaking changes that are not covered in this table. | Read the release notes for every version on the path, record each breaking change against your customizations, and retest after each hop. |
How the supported upgrade path works one hop at a time
Each major version of ERPNext has to be installed, migrated and checked before you move to the next one. A site on version 13 cannot jump straight to version 16 in one step, because each major release carries its own schema changes, app splits and migration logic that assume the previous release has already run. The practical plan is a sequence of hops, with a working, tested site at the end of each one, and with the customizations and companion apps for that version confirmed before the next hop starts.
Start by checking the supported versions page at Supported versions for Frappe products. It lists which ERPNext and Frappe Framework versions are supported and when each support window ends. Confirm the current status on that page on the day you pin your plan, because support dates shape which target is realistic. Frappe's supported versions policy also states that a customer must run a listed version and hold a matching Frappe Cloud support plan to receive warranty coverage from Frappe. If you self-host outside Frappe Cloud, ask your partner and Frappe how that condition applies to your setup before you commit to a target.
Minor releases arrive often. The release history shows v16.51.1 and v15.123.0 published within a day of each other in October 2026, so a target that is not pinned will move while the project runs. Choose one specific minor release for each hop at the start, record it in the project plan, and test every hop against that exact version. Apply later minor updates only after the migration is closed, using a separate test site. Ask your partner to confirm which minor release it will test against and how it will handle any release that ships during the project.
What to prepare before touching the v13 site
Four to six artifacts have to exist before anyone runs a migration step on the version 13 site. Each one gives the team a way back, a way to test, or a way to prove the data survived. Together they turn the upgrade from a single risky event into a sequence of checked hops.
Tested full backup and restore
A backup that has never been restored is an assumption, not a recovery plan. Take a full database and file backup of the v13 site, restore it to a separate host, and confirm the site loads, logs in and opens key documents. Record how long the restore took and who ran it, because the same procedure is the rollback path if a hop fails.
Inventory of customizations
List every custom field, client script, server script, custom app, print format, report and web form on the site, with its owner and purpose. Mark which ones were built for version 13 behavior and which ones are still needed. Server Scripts are disabled by default from version 15 and must be enabled with server_script_enabled, so flag any script that depends on them before the first hop.
Cloned test environment
Build a non-production copy of the v13 site from the latest verified backup, on infrastructure that matches production in database engine, Python and Node versions, and reachable services such as email and LDAP. Run each upgrade hop there first. Keep the clone isolated from live email, payment and integration endpoints so test runs cannot send real messages or post real transactions.
Installed apps and matching branches
Record every installed app, its source repository, its current branch or tag, and the Frappe version it targets. Apps that split from ERPNext in version 14, such as Frappe HR and India Compliance, must move with the core in step, so the team needs a written pairing for each hop. Confirm each branch exists for the target version before scheduling the work.
Agreed data reconciliation checklist
Agree in writing which numbers must match after every hop: general ledger totals by company and period, open receivables and payables, stock valuation by warehouse, and counts of key documents such as invoices, orders and employees. Name the person who signs off each check. Without a shared checklist, a broken migration can pass technical tests and still misstate the books.
The upgrade sequence, with a check and rollback point at each hop
The sequence moves a version 13 or older ERPNext site through one major version at a time, with a verified backup and a rollback point before every hop. Each step closes with a check that tells you whether the next hop is safe to start.
Freeze the test clone of production
Create a test copy of the production site on a separate bench or server, and stop all changes to production data and customizations for the duration of the upgrade rehearsal. Record the exact ERPNext, Frappe and app versions in use, along with the list of custom apps, Server Scripts, Client Scripts, custom fields and print formats. The clone is the place where every hop is rehearsed first. It is done when the version inventory is written down and the clone matches production in data and code.
Take and verify backups before each hop
Take a full database and files backup of the site before touching any version, and store a copy outside the server being upgraded. Restore that backup to a scratch environment to confirm it is readable and complete. Repeat this before every hop, not only the first, so each step has its own restore point. The step is done when a restore has been tested and the backup is labeled with the version it came from.
Upgrade to version 14 with companion apps installed
Move the test clone to ERPNext version 14 using the matching branch of each app, and install the companion apps that split out in that release, including Frappe HR where your site uses it. For Indian GST sites, migrate to India Compliance as part of this hop, following the India Compliance migration guide for sites coming from version 13 and its requirement of Frappe version 14 or above. The step is done when the migrate completes without errors and every installed app reports a version that matches the ERPNext release.
Run data checks after the version 14 hop
Compare record counts, open and submitted document totals, ledger balances, stock valuation and outstanding receivables and payables against the pre-upgrade figures you captured in the freeze step. Check that GST returns, tax templates and item tax settings still produce the same results on sample invoices. Investigate every difference before continuing. The check passes when the totals match or each variance has a documented cause and an accepted fix.
Retest customizations at version 14
Walk through each custom DocType, Server Script, Client Script, custom field, report and print format on the upgraded clone, using the test cases written for them. Confirm that Server Scripts still run where your environment allows them, and that any hooks in custom apps still fire on the document events they target. Log every failure with its owner. The step closes when every customization has passed its test or has a tracked fix, and the team signs off that the site is ready for the next hop.
Repeat the cycle for version 15
Take a fresh backup of the version 14 clone, then move to version 15 with the companion apps that split out in that release installed and matched to the same branch. Note that Server Scripts are disabled by default from version 15 and must be enabled deliberately with the server_script_enabled setting, so review each script against that change. Run the same data checks and customization retests as before. The hop is complete when the checks pass and the rollback point for version 15 is recorded.
Repeat the cycle for the chosen final version
Repeat the backup, upgrade, data check and retest cycle for the final version you have selected, which may be version 15 or version 16. Review custom apps against the version-specific changes that apply to that release before you start. Once the final hop passes, rehearse the production cutover on the clone, including the order of migrate, cache clearing and app restarts. The step is done when the rehearsal produces the same data checks as the earlier hops and the production cutover plan is written and agreed.
Confirm the rollback path for production
Before cutover, confirm that the backup taken immediately before the production upgrade has been restored successfully to a scratch environment, and that the team knows how to return the site to its previous version using that backup. Agree who makes the rollback decision and the conditions that trigger it, such as failed data checks or broken critical workflows. The sequence is complete when production is upgraded, the data checks pass on production and the rollback procedure is documented for the first days of live use.
Data checks between hops that catch problems early
Ledger balances are the first thing to compare because a silent change here affects every report and every period already closed. Before each hop, export a trial balance, the general ledger for a fixed date range, and the outstanding balances for receivables and payables. Run the same exports on the upgraded test copy and compare totals by account, company and currency, not just grand totals, so that offsetting differences do not hide each other.
- Trial balance by account: Compare every account and company, including closed fiscal years, before and after the hop.
- Outstanding invoices and payments: Confirm that open receivables and payables match by party and currency, with no unallocated payments appearing or disappearing.
- Journal entry counts and totals: Check that the number of entries per period and their debit and credit totals are unchanged.
- Period closing vouchers: Verify that closed periods still report the same results and that no entries can be posted into them by accident.
- Currency and exchange rate records: Confirm that stored exchange rates and gain or loss postings were not recalculated.
Sign-off: the finance controller or accounting lead signs off, with the platform owner attaching the exports.
Stock data changes shape between major versions as serial and batch handling and valuation logic evolve, so compare quantities and values rather than assuming migration scripts preserved them. Use stock balance and stock ledger reports for each warehouse and item group, and compare the valuation of each item before and after the hop. Where a batch or serial correction is needed, plan it as a controlled reload and not as ad hoc edits in the desk.
- Stock balance by warehouse: Compare quantity and value for every warehouse and item at a fixed cut-off date.
- Stock ledger entries: Check the count and total of entries per item and voucher type.
- Serial and batch records: Confirm that each serial number and batch still maps to one item, one warehouse and the expected quantity.
- Valuation method and rates: Verify that the valuation method and the incoming rates for recent purchase receipts are unchanged.
- Reserved and pending quantities: Check open sales orders, work orders and material requests against reserved stock.
If a re-load is needed for master or transactional stock data, split the file into batches of a few thousand records, since the Data Import tool documentation advises importing only a few thousand records at a time. Sign-off: the warehouse or operations lead, with the finance lead confirming valuation.
Tax data is where version gaps cause the most avoidable rework, especially for Indian GST setups. The India Compliance app documentation includes a migration guide for sites moving from version 13, and its installation guide asks for Frappe version 14 or above, so confirm the matching India Compliance release for each hop before comparing any tax figures. Compare tax totals by tax template, GSTIN and period, and confirm that e-invoice and e-way bill fields still populate on recent documents.
- Tax totals by template: Compare taxable value and tax amounts per tax account and period.
- GSTIN and party tax details: Check that customer and supplier GSTINs, tax categories and place of supply are unchanged.
- E-invoice and e-way bill fields: Confirm that identifiers and status fields on recent invoices are still present.
- Return and reconciliation reports: Compare the figures the tax team uses for filing preparation before and after the hop.
- Tax account mapping: Verify that every tax account still points to the intended ledger account.
Sign-off: the tax or GST compliance owner signs off, and the finance lead confirms that tax ledger balances still agree with the accounting checks.
Master data such as items, customers, suppliers, price lists and users rarely breaks loudly, but a changed default or a missing role can stop a business process on the first day after go-live. Export counts and key fields for each master DocType, and compare user records, roles and permissions with the access model you intended. Check user logins against your identity source if you use LDAP or social login, because login behavior can change with the version and the authentication settings.
- Record counts by DocType: Compare counts for items, parties, addresses, price lists and users before and after the hop.
- Key field comparison: Check naming series, item groups, default accounts and default warehouses on a sample of records from each master.
- Roles and permissions: Confirm that each user has the same roles and that user permissions still restrict data by company and warehouse.
- Login paths: Test password login, two-factor authentication and any LDAP or social login configured for the site.
- Scheduled emails and integrations: Verify that the users who receive reports and alerts still exist and are active.
Sign-off: the business process owners for sales, purchasing and HR sign off their master data, and the security or identity owner signs off access.
Customizations are the most likely source of failures between hops because custom fields, scripts and print formats depend on internal behavior that changes across versions. Inventory every custom field, client script, server script, custom app, print format, report and workspace before the first hop, and record which ones are expected to work unchanged. Server Scripts are a specific case: according to the Frappe Framework documentation, they are disabled by default from version 15 and must be enabled with the server_script_enabled setting, so a script that ran before can silently stop running after the hop.
- Customization inventory: List every custom field, script, print format and report with its owner and purpose.
- Script execution tests: Trigger each document event and API endpoint that a script handles, and compare the results with the pre-upgrade test copy.
- Server Script setting: Confirm the state of server_script_enabled after each hop and where that setting is allowed to change.
- Print formats and reports: Render each important print format and report and compare layout and totals.
- Custom app versions: Confirm that each custom app has a branch that matches the target version before running migrate.
Sign-off: the application owner or development lead signs off each customization, and the platform owner confirms the settings and app versions used in the test run.
Questions buyers ask before upgrading ERPNext from v13
What drives the cost of upgrading ERPNext from version 13?
The cost is driven by how many major versions you must pass through, how much custom code and how many companion apps you run, and how much data needs checking at each step. Each hop from v13 to v14, and then to v15 or v16, carries its own migration, testing and sign-off work. Costs are typically split into a one-time assessment, one-time upgrade and retest work per hop, and ongoing support afterward. Ask any provider for a quote that lists each hop separately, the custom apps and customizations in scope, the companion apps to be kept in step, the test cycles, and who signs off data checks. Figures for your environment can only come from that written scope.
How long does an upgrade from ERPNext v13 take?
Duration depends on the number of hops, the size of your database, the number and complexity of customizations, and how many sites and apps run on the bench. Each major version step needs its own migration, regression testing and data validation before the next one starts, so the work is sequential rather than parallel. Your timeline should include an assessment of current customizations, a test site for each hop, and a production cutover window with a tested rollback. Confirm the schedule against your own change-freeze periods and the support status of your current version before committing to a date.
What does the upgrade need from our internal team?
The work needs a named business owner for accounting, stock and any other module in use, a technical owner for the bench, servers and backups, and access to a staging copy of production. Business users must confirm the data checks at each step, such as ledger totals, stock balances and open documents, because a technical pass alone does not prove the books are right. Your team should also own the decisions on which customizations to keep, rewrite or retire. Ask the provider to list these roles and the time each one is expected to commit in the written scope.
Can our own team upgrade ERPNext from v13 without a partner?
An internal team can do it if it has people who understand the Frappe bench, database backups and restores, Python for custom apps, and the accounting and stock configuration of your company. The main risks are untested customizations, skipped data checks between versions, and missing companion apps. A useful test is whether your team can rebuild a staging site from production, run each migrate step, and reconcile key reports against the pre-upgrade figures. If any of those steps is unfamiliar, a fixed-scope engagement can cover the gaps while your staff keep ownership of the business sign-off.
Does India Compliance change the upgrade plan for Indian GST sites?
Yes. India Compliance is a separate app, so it must be installed and matched to the correct Frappe and ERPNext version at each hop, not left to migrate on its own. The India Compliance documentation includes a migration guide for sites moving from version 13 and asks for Frappe version 14 or above at installation. Plan GST-specific tests, including e-invoice and return data, GSTIN validation and tax templates, on a test site after each step. Confirm the app version pairing and the migration steps in the India Compliance documentation before scheduling production work.
Should we skip version 14 and go straight to version 15 or 16?
Going straight from v13 to a later version is not a supported path in the way that a single hop is, so plan each major version in sequence unless the release notes for your target explicitly describe a direct migration. Version 14 reached end of life on January 31, 2026, according to Frappe's supported versions page, so the question is less about skipping and more about which supported version to land on. Version 15 is planned to be supported until the end of 2027 and version 16 until the end of 2029, per the same page. Choose the target by weighing your support window, your custom app compatibility and your team's capacity to retest, then confirm the migration path with the release notes and your provider.
What support do we need after the upgrade is complete?
After cutover you need a plan for minor releases, backups before each update, and a test site where changes are checked first. Both supported major versions receive frequent minor releases, so an update routine is part of ongoing operations rather than a one-time event. Frappe's supported versions policy says customers must be on a listed version and subscribed to a matching Frappe Cloud support plan to receive warranty coverage from Frappe, so confirm which support arrangement applies to your hosting. Ongoing support, upgrades and testing can be contracted as a retainer, and the scope should state response expectations in writing.
What makes a v13 upgrade longer or shorter
This table lists the factors that most change the effort of a multi-step upgrade from ERPNext v13 or earlier, along with what each one affects and what to check first. Read each row against your own site inventory, since several drivers compound each other when they appear together. The main takeaway is that custom code and localization setups usually matter more than site count.
| Effort driver | Why it changes the work | What to check |
|---|---|---|
| Number and type of customizations | Custom fields, client scripts and server scripts can break when DocTypes, fields or APIs change between versions | Export customizations, list each one, and note which depend on fields or methods removed in a later version |
| Custom apps and upstream maintenance | An app with no maintainer on the target version must be ported or replaced before any hop can finish | Confirm each app has a branch for every version in your path and who will fix it when a hop breaks |
| Companion apps in use | Apps split out in v14 or later, such as Frappe HR, must be installed at matching versions at each step | List every installed app, its source branch, and whether it is still needed on the target version |
| Indian GST or other localization setups | GST configuration moves to India Compliance, so tax settings and reports need a planned migration and retest | Confirm whether India Compliance is installed, the Frappe version it requires, and which GST reports your filings depend on |
| Data volume and history | Large ledgers and stock histories take longer to migrate and check between steps | Measure record counts for key DocTypes and plan data checks at each hop, not only at the end |
| Number of sites | Each site runs its own migrate, backups and tests, so effort scales with site count and variation between sites | Identify which sites share apps and customizations and which differ |
| Deployment method (bench, frappe_docker or Helm) | Bench upgrades run on the host, while Docker and Helm rebuild images or run migrate jobs per site | Confirm the method in use, how images or app versions are pinned, and where backups are stored |
Testing and rollback when a hop fails
Run every hop first on a test site restored from a fresh copy of production, never on production itself. The copy should carry the same ERPNext and Frappe versions as the source, the same installed apps including *Frappe HR* and *India Compliance* where they apply, the same custom apps, and a representative slice of live data, including GST-registered customers, tax templates and open invoices. Before each hop, rebuild the test site from the backup taken at the start of that hop, so that a failed run in the previous step does not contaminate the next. Confirm with your partner or internal team how long a restore of your largest site takes, because that figure determines whether the test cycle fits your cutover window.
Retest customizations at every hop, not just at the end. Custom fields, Server Scripts, Client Scripts, print formats, reports and custom apps can break at a different version each time. Server Scripts in particular depend on the server_script_enabled setting, which is disabled by default from version 15, so confirm that setting on each test site before you judge a script's behavior. Keep a written test list per hop covering invoicing and tax calculation, stock entries, payroll postings where Frappe HR is in use, and any integration that writes to ERPNext. Record the result of each check so the next hop starts from a known state.
Decide between fixing forward and restoring the backup using predefined criteria agreed before the cutover. Fixing forward suits a failure that is isolated, reproducible on the test site and fixable with a patch or a configuration change within the agreed window. Restoring suits data corruption, failed migrations that leave the schema half-changed, or any hop where the fix needs an unreviewed workaround on live data. Every hop needs its own rollback point: a full database and file backup taken immediately before that hop's bench migrate, verified by a test restore. Rolling back to the start of the whole project discards the work of every earlier hop, so a single pre-project backup is not enough.
Decisions to settle before the first hop
A multi-step upgrade from version 13 or earlier multiplies every choice, because each hop repeats the work. Settle these four questions before the first migration runs, since each one changes the test plan, the build pipeline and the people who must approve the result.
Target version and end-of-life dates
Decide whether the final destination is version 15 or version 16, and map each intermediate hop in between. Version 14 reached end of life on January 31, 2026, so any site still on it has no upstream fixes. Version 15 is planned for support until the end of 2027 and version 16 until the end of 2029. Confirm the choice against your own risk tolerance and release calendar before you plan the hops.
Deployment method for the target
Choose how the final site will run: bench on Linux, Docker with frappe_docker, or Kubernetes with the Helm chart. The method decides how each hop is built, how migrations run and how rollback works. Containers are rebuilt for each version rather than patched in place, so a Docker or Kubernetes team needs an image pipeline ready before the first hop. Confirm which method your operations team can support for the next several years.
Keep or retire customizations
Inventory every custom field, script, custom app, print format and report, then decide which ones to keep, rebuild or drop. Retire what the core now covers before you port it, because each kept customization must be retested at every hop. Server Scripts are disabled by default from version 15 and must be enabled with server_script_enabled, so any script logic that depends on them needs an explicit decision.
Owner of data check sign-off
Name one business owner per area, such as accounting, stock and payroll, who signs off the reconciliation after each hop. Technical staff can confirm that migrations completed, but only the finance and operations owners can confirm that balances, open documents and tax figures match the source. Agree the sign-off criteria and the sign-off record in writing before the first hop, so a failed check has a clear owner and a clear stop decision.
How DeployOpen scopes, delivers and supports an ERPNext upgrade
DeployOpen treats an upgrade from ERPNext version 13 or older as a planned series of single-version hops, each with its own app matching, customization retest and data checks. We work inside your own infrastructure, and the written scope sets which hops, apps and customizations are in and out before any work starts.
How we scope
- Inventory of your current version, sites, installed apps and customizations, including any Indian GST setup that needs a migration to India Compliance
- Written scope listing each version hop, the companion apps to install at each step and the customizations to retest
- Agreed list of data checks between steps, such as ledger and stock reconciliation against pre-upgrade reports
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts
How we build
- Staging copies of your production sites so each major version step runs and is tested before production is touched
- Matching companion app branches installed before each migrate, with customizations retested at every hop
- Backups taken before each step, with a rollback procedure written and rehearsed for every version boundary
- Build and test records kept per hop, so each change is traceable to a specific version and app release
How we hand over
- Runbook for each hop covering commands, app versions, migration output and the checks that passed
- Updated record of customizations, custom apps and integrations, with the retest result for each one
- Walkthrough with your administrators and developers so they can run the next step without us
- Documentation of open items, such as end-of-life dates and the version you plan to land on
How we support
- Post-upgrade support with a clear boundary between the closed project and any ongoing work
- Ongoing support, upgrades and continuous testing available as a retainer, scoped in writing
- Periodic review of minor releases and app versions on the version you run, with changes tested on a copy first
- Confirm with DeployOpen which support window and version policy applies to your site before planning the next upgrade
