Immanuel Raj

3D isometric illustration showing a server migration process, with data flowing through a glowing blue pathway from an old server rack to a modern high-performance server tower, symbolizing the Frappe v15 to v16 upgrade.

Migrating from Frappe v15 to Frappe v16 Beta — A Complete, In‑Place Upgrade Guide

—

by

Immanuel Raj
in ,

Upgrading between major Frappe versions is always a big moment, especially when you want a clean, in-place migration without resetting or recreating anything. With the release of Frappe Framework v16.0.0‑beta.1, we finally get the first look at what’s coming — a brand‑new UI, navigation overhaul, performance upgrades, and several structural changes. But since this is a beta release, there’s no official migration guide yet.

This article covers everything you need to know to migrate safely from Frappe v15 → v16 Beta, including prerequisites, breaking changes, new dependency requirements, handling custom apps, and installing the new Offsite Backup app. It’s written from real‑world experience and based entirely on the official changelog and merged pull requests in the beta release.

🔧 Prerequisites Before Migrating

Before switching branches, ensure your system meets the new minimum requirements introduced in Frappe v16:

1. Python 3.12

Frappe v16 drops support for older Python versions. Your environment must run Python 3.12.

2. Node.js 22

Node 18 (or lower) won’t work. Update to Node.js 22 LTS before building assets.

3. Latest MariaDB / Redis (Recommended)

Not mandatory but highly recommended for performance and compatibility.

4. Ensure Your Bench is Updated

pip install --upgrade frappe-bench

🔥 Highlight Features & Changes in Frappe v16

Before diving in, note that the changes listed below include both highlights from the official v16 beta changelog and the improvements I personally consider the most important and attention‑worthy.
Here are the changes directly extracted and interpreted from the v16 β changelog and PRs.

1. SQLite Support — Run Frappe Without a Separate Database

One of the biggest structural changes in Frappe v16 is native SQLite support.

You can now run Frappe with only SQLite, without requiring MariaDB.
This completely changes how lightweight deployments, dev setups, and local experiments can be done.

Benefits:

  • No external DB dependency
  • Faster test environments
  • Easier local development
  • Simplified deployments for small apps

This is one of the most impactful backend changes in Frappe 16.

2. A Completely New UI & Navigation System

Frappe v16 ships with a fully redesigned interface:

  • New layout structure
  • New menu system
  • New URL routing pattern
  • Cleaner, modular page design

This is the biggest UI jump since v12 → v13.

2. Major URL Pattern Changes (Important!)

The old style URLs change significantly.

A standout improvement:

  • #tab_x URLs now point directly to individual elements, making deep‑linking smoother.

3. Events for Table MultiSelect

The new event system introduced for Table MultiSelect fields adds:

  • Real‑time event hooks
  • Better dynamic behavior
  • Cleaner custom logic

This is especially useful in customization-heavy apps.

4. Users Can Now Have Multiple Roles (PR #26394)

This is a big one.

Previously, assigning multiple roles required creating a Role Profile or relying on workarounds. Now:

  • Users can directly have multiple roles assigned
  • No role profile needed for simple role combinations

This significantly reduces clutter in permissions setups.

5. New Image Field Preview (PR #31719)

The new image preview improvements make media handling smoother.
This benefits:

  • CMS use‑cases
  • E‑commerce
  • Anything involving file/image uploads

6. Removal of Google Drive & S3 Backup Integrations

Frappe has completely removed:

  • Google Drive Backup
  • S3 Backup

These are now moved into a separate official app:
👉 https://github.com/frappe/offsite_backups

To continue remote backups, you must install this app after migrating.

7. Performance Optimizations

A major portion of the beta changelog is focused on internal improvements:

  • Faster build times
  • Optimized caching
  • Improved doc-type rendering
  • Reduced desk load operations
  • More efficient API responses

These enhancements collectively make the framework feel significantly smoother.

8. Additional Notable Changes from the Beta Changelog

After reviewing the official release notes for v16.0.0-beta.1, here are more updates worth mentioning:

  • Enhanced desk rendering logic and navigation structure
  • More consistent form behavior with updated controllers
  • Improved event handlers across multiple field types
  • Several security fixes and permission cleanup PRs
  • Changes in how sidebar & workspace items load
  • Better error reporting and debugging hooks

While not always visible, these changes contribute directly to better stability and developer experience.**
A large portion of merged PRs focus on:

  • Query optimization
  • Faster server‑side operations
  • Improved desk performance
  • Reduction of redundant calls

This is not just a UI release — there is real backend improvement.

🧩 Custom Apps — Important Migration Notes

If your bench has custom apps, pay extra attention.

1. Update the Frappe Dependency in Each App

Inside every custom app’s setup.py or pyproject.toml, update:

frappe>=16.0.0-beta.1

If your app depends on frappe>=15, the migration will break.

2. Install Beta Releases for Other Frappe Apps

Frappe also released v16 betas for:

  • ERPNext
  • HRMS

If your site depends on these, install/upgrade them before switching branches.

Example:

bench get-app erpnext --branch v16.0.0-beta.1
bench get-app hrms --branch v16.0.0-beta.1

3. Validate Custom Scripts & Patches

With the new UI and URLs, review:

  • Custom JS scripts
  • Page overrides
  • Link formats
  • URL-based routing

Anything touching the Desk may require updates.

🛠️ Migration Steps — v15 → v16 Beta (In‑Place, No Reset)

Here is the cleanest method to migrate without resetting or recreating anything.

Step 1: Take a Full Backup

bench backup --with-files

Step 2: Upgrade Python & Node (if needed)

Reinstall environment with Python 3.12:

pyenv install 3.12.x  # or system install

Upgrade Node:

n# (Node version manager)
n install 22

Step 3: Update Dependencies of Custom Apps

Update the Frappe requirement in the app config files.

Step 4: Switch Frappe Branch to v16 Beta

bench switch-to-branch v16.0.0-beta.1 frappe

If using ERPNext or HRMS:

bench switch-to-branch v16.0.0-beta.1 erpnext
bench switch-to-branch v16.0.0-beta.1 hrms

Step 5: Install Offsite Backup App

Since v16 removes GDrive & S3 backups:

bench get-app https://github.com/frappe/offsite_backups
bench --site yoursite.com install-app offsite_backups

Step 6: Run Migrate

bench update --patch
bench migrate

Step 7: Build Assets

bench build

Step 8: Restart Services

bench restart

🧪 Beta Status — What to Expect

Since this is a beta:

  • Some modules may not behave as expected
  • Fixtures & custom apps may need adjustments
  • More PRs will land during the beta cycle

Always test on a staging server before moving production.

🎉 Final Thoughts

Migrating to Frappe v16 is more than a version upgrade — it’s stepping into an entirely new UI and navigation system. The improvements in permissions, performance, URL structure, and developer ergonomics make it a significant milestone.

If you follow the steps above — updating dependencies, installing the new backup app, and switching branches properly — you can complete the migration without wiping or recreating your site.

Once stable releases arrive, the ecosystem around v16 will become even more polished. Until then, enjoy exploring the beta and all the new capabilities it offers.

Read about adding custom reset template for frappe
Read about my custom app to harden frappe login