Upgrade from v12 to v13 or later, with customizations


I have inherited an ERPNext system setup by Developers who have left my company.

The ERPNext is version 12.14 and Frappe is version 12.12. Bench is version 5.0

The server is Ubuntu 18 in an AWS Lightsail VM, and the database is an AWS RDS using Maria DB v10.1

A large number of customizations have been created for ERPNext including many new DocTypes and modifications to some existing DocTypes.

My question is, what is the best way to upgrade this system?

I have read a number of threads on here regarding upgrade processes but none of them explain clearly how to persist customisations. Also, many of the guides that refer to database migrations seem to assume the database is hosted on the application server rather than being hosted separately.

I would appreciate a top-level description of how to upgrade a customised ERPNext with my architecture. Thanks.

@corinja you need to store all your customization in your custom app. migrating from 12 to 13 or 14 with multiple customizations is a big mess. for me I just kept the version 12 running and installed another server running version13 . (you need to upgrade many packages). then I restored my backup files and customizations .

Thanks for your reply.

Can you direct me to documentation on how to store our customizations? Is this where we need to use Fixtures? Do we need to fork the erpnext repo or can we just do this with bench commands?

To backup our site, can I run the bench backup command even though our database is remotely hosted?

1 Like

Hi Corinja,
Hope you are enjoying erpnext! If you need an immediate and paid solution then you can contact us.

Contact Details:
Noman Haider, CEO
+8801973884424 (WhatsApp)

Thanks Noman. If necessary I will contact you.

Seems there are two different approaches to customisation in frappe/erpnext

One is to create a custom app and use fixtures to record changes made such as DocTypes via the UI. Then use bench to apply these changes.

The other is to branch (or fork) the erpnext repo and just use native git commands to track changes, in order to re-apply them after pulling the main version branch changes.

Can someone confirm or disconfirm if my understanding is correct? If not, can it be explained to me?

Hi @corinja ,

You are very close: there are 3 approaches.

  1. Make changes using the “Customize” button, Client Scripts, and Server Scripts without a custom App.

    • With this approach, the changes are saved inside the MariaDB database itself. They are not saved in the git repository.
  2. Make changes using a custom App, using things like hooks, fixtures, etc.

    • Your changes are saved to disk, and will become part of your custom App’s git repository.
    • This was the first approach you mentioned.
  3. Fork the frappe and/or erpnext Apps, make your modifications directly. When it comes time to upgrade, you merge your changes with the latest, official code.

Most forum users will recommend Option 2. (personally I prefer forks, so always use Option 3)

FYI, the minimum Python version is different starting in ERPNext v14. If you’re going to upgrade to v14 or v15, you need to first address that. Either by installing the new Python on the same droplet (so that 2 versions of Python coexist). Or by deploying a new droplet for your new ERP version (Ubuntu 22.04, or Debian 12)


Thank you very much @brian_pond for that very useful and informative reply.

So, it seems the previous developers who worked on my ERPNext system used the first approach, creating & modifying DocTypes using the Customize UI feature. I can see the changes have been saved into the erp schema of the MariaDB.

However, when I try to run bench update I get the error:

Updating apps source...                 

Cannot proceed with update: You have local changes in app "erpnext" that are not committed.

I get the same error with the frappe app itself, and running git status I can see files that have changed in there also:

/frappe-bench/apps/frappe$ git status
On branch version-12
Your branch and 'upstream/version-12' have diverged,
and have 24078 and 1 different commits each, respectively.
  (use "git pull" to merge the remote branch into yours)

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   frappe/contacts/doctype/contact/contact.json
	modified:   frappe/core/doctype/doctype/doctype.json
	modified:   frappe/integrations/doctype/social_login_key/social_login_key.json
	modified:   frappe/utils/oauth.py

I assumed this was because changes made using the UI Customization feature changed both the database schema and the source code for e.g. doctype or for authentication features we have activated like SSO.

I think this means I will have go with option 3 from your list of approaches, in order to track and preserve whatever changes these are.

(I’m working on a copy of our staging environment initially so I have an expendable development environment to try this out on.)

1 Like