How to Upgrade ERPNext Version 15 to Version 16: Complete Step-by-Step Guide (2025)

Upgrade ERPNext version 15 to 16 with this complete guide designed for businesses, IT teams, and ERP administrators.

Upgrading from ERPNext v15 to v16 brings significant improvements: 2x faster performance, customizable financial statements, enhanced manufacturing features, and a completely redesigned workspace. But a successful upgrade requires careful planning and execution.

This comprehensive guide walks you through every step of upgrading ERPNext from version 15 to version 16, whether you’re managing the upgrade yourself or working with an implementation partner.

If you’re planning a DIY upgrade, make sure you review our ERPNext v15 to v16 upgrade guide before starting.

Why Upgrade to ERPNext Version 16?

Before diving into the technical process, it’s important to understand why most businesses are planning to upgrade ERPNext version 15 to 16 this year. For a full breakdown of all new features, see our complete ERPNext version 16 release notes.

Performance Improvements

2x Faster Performance: Built on Frappe Framework v16’s Caffeine architecture, which delivers approximately 2x performance improvements across the board:

• Faster page loads
• Quicker report generation
• Smoother list view rendering
• Reduced server resource consumption

For businesses processing hundreds of transactions daily, this performance boost translates to real productivity gains. To take advantage of all these improvements, it’s important to upgrade your ERPNext installation to v16.

Financial Management Enhancements

Customizable Financial Statements: The biggest accounting improvement in years. You can now:

• Customize balance sheets and P&L statements to match your business structure
• Create industry-specific financial reports
• Adjust report layouts without custom code
• Generate consolidated financial statements across multiple companies

Enhanced Budgeting: Better budget tracking, variance analysis, and multi-dimensional budgeting capabilities.

Refactored TDS (Tax Deducted at Source): Simplified Indian tax compliance with improved TDS calculation and reporting.

Manufacturing & Inventory Upgrades

Inward Subcontracting: Track materials sent to subcontractors and finished goods received back, with full inventory visibility.

Stock Reservation: Reserve inventory for specific sales orders or projects, preventing overselling and improving fulfillment accuracy.

Enhanced MRP: Smarter material requirement planning with better demand forecasting and procurement suggestions.

You can access these enhanced manufacturing features by upgrading to ERPNext v16.

User Experience Improvements

Redesigned Workspace: Modern, intuitive interface with improved navigation and customizable module cards.

Enhanced List Views: Scrollable, resizable columns that can display unlimited fields without performance degradation.

Role-Based Field Masking: Automatically mask sensitive fields (salary, bank details, etc.) based on user permissions.

Before You Begin: Pre-Upgrade Checklist

A successful upgrade starts with thorough preparation. Complete this checklist before touching your production system.

1. Review System Requirements

Server Requirements for ERPNext v16:

• Operating System: Ubuntu 20.04 LTS or 22.04 LTS (recommended)
• Python: 3.10 or higher
• Node.js: 18.x or higher
• MariaDB: 10.6 or higher
• Redis: 6.x or higher
• RAM: Minimum 4GB (8GB+ recommended for production)
• Storage: At least 20GB free space for upgrade process

Check your current versions:

bench version
python3 –version
node –version
mysql –version
redis-server –version

If your server doesn’t meet these requirements, you’ll need to upgrade your infrastructure first. For detailed server specs and deployment guidance, review our complete ERPNext hosting requirements.

2. Audit Custom Apps and Customizations

List all installed apps:

bench –site [your-site-name] list-apps

Document your customizations:

• Custom DocTypes
• Custom fields added to standard DocTypes
• Custom scripts (client scripts, server scripts)
• Custom reports
• Custom print formats
• Workflow customizations
• Custom integrations

Test custom app compatibility: Contact the developers of any third-party apps to confirm v16 compatibility. Most well-maintained apps will have v16-compatible versions ready by the final release date (December 6, 2025).

3. Create Complete Backups

Never upgrade without backups. You need multiple backup types:

Database Backup:

bench –site [your-site-name] backup –with-files

This creates a database backup and includes uploaded files.

Full Site Backup:

bench –site [your-site-name] backup –with-files

Bench Directory Backup:

cd ~
tar -czf frappe-bench-backup-$(date +%Y%m%d).tar.gz frappe-bench/

Store backups in multiple locations:

• Local server (different partition)
• Cloud storage (AWS S3, Google Cloud Storage, Dropbox)
• External hard drive (for critical systems)

Verify your backups: Try restoring to a test environment to ensure backups are valid.

4. Set Up a Staging Environment

Never upgrade production directly. Always test in staging first.

Option A: Clone your production environment:

# Create new site from backup
bench –site staging.yourcompany.com restore /path/to/backup.sql.gz

Option B: Use a separate server: Ideal for large deployments. Set up a complete replica of your production environment.

Test everything in staging:

• Upgrade process
• Custom app functionality
• User workflows
• Integrations
• Reports
• Print formats

5. Plan Your Upgrade Timeline

Choose the right time:

• Avoid month-end/quarter-end: Financial closing periods are high-risk times.
• Weekend or off-hours: Minimize user disruption.
• Low transaction volume periods: Easier to verify data integrity.
• Allow buffer time: Plan for 2-3x longer than estimated.

Make sure you factor in the upgrade process from v15 to v16 when estimating total upgrade time.

Typical upgrade timelines:

• Small deployment (1-10 users, minimal customization): 2-4 hours.
• Medium deployment (10-50 users, moderate customization): 4-8 hours.
• Large deployment (50+ users, heavy customization): 8-24 hours.
• Enterprise deployment (multi-site, complex integrations): 1-3 days.

6. Communicate with Stakeholders

Notify all users at least 1 week in advance:

• Scheduled downtime window
• Expected duration
• What to expect after upgrade
• Who to contact for issues

Prepare your support team:

• Review new features
• Identify potential user questions
• Have rollback plan ready
• Establish communication channels

Step-by-Step Process to Upgrade ERPNext Version 15 to 16

Now let’s walk through the actual upgrade process. These instructions assume you’re using Frappe Bench on a Linux server. If you’re unsure where to begin, our full guide explains how to upgrade to ERPNext v16 in a structured and safe way

Step 1: Update Bench and Dependencies

Switch to your bench directory:

cd ~/frappe-bench

Update bench utility:

pip3 install –upgrade frappe-bench

Update system packages:

sudo apt update && sudo apt upgrade -y

Step 2: Backup Everything (Again)

Yes, backup again immediately before starting:

bench –site [your-site-name] backup –with-files

Verify the backup was created:

ls -lh ~/frappe-bench/sites/[your-site-name]/private/backups/

Step 3: Switch to Version 16 Branch

Update Frappe Framework to v16:

bench switch-to-branch version-16 frappe –upgrade

Update ERPNext to v16:

bench switch-to-branch version-16 erpnext –upgrade

Update HRMS to v16 (if installed):

bench switch-to-branch version-16 hrms –upgrade

Update custom apps: For each custom app, switch to its v16-compatible branch:

bench switch-to-branch [branch-name] [app-name] –upgrade

Step 4: Install Dependencies

Install Python dependencies:

bench setup requirements

Install Node.js dependencies:

bench setup requirements –node

This may take 10-20 minutes depending on your internet connection.

Step 5: Build Assets

Build frontend assets:

bench build

This compiles JavaScript, CSS, and other frontend resources. It typically takes 5-15 minutes.

Watch for errors: If the build fails, check error messages carefully. Common issues:

• Insufficient memory (add swap space)
• Node.js version incompatibility
• Corrupted node_modules (delete and reinstall)

Step 6: Migrate Database

Run database migrations:

bench –site [your-site-name] migrate

This is the critical step that updates your database schema to v16 structure.

What happens during migration:

• New tables are created
• Existing tables are modified
• Data is transformed to new formats
• Indexes are rebuilt
• Constraints are updated

Migration duration varies:

• Small database (<1GB): 5-15 minutes
• Medium database (1-10GB): 15-60 minutes
• Large database (>10GB): 1-4 hours

Monitor migration progress: The migrate command shows progress. Don’t interrupt it.

If migration fails:

• Review error messages
• Check database logs
• Restore from backup and troubleshoot
• Contact support if needed

See the official ERPNext upgrade notes.

Step 7: Clear Cache and Restart

Clear all caches:

bench –site [your-site-name] clear-cache
bench –site [your-site-name] clear-website-cache

Restart bench:

bench restart

Step 8: Verify the Upgrade

Check installed versions:

bench version

You should see:

• Frappe Framework: version-16
• ERPNext: version-16
• HRMS: version-16 (if installed)

Log in to ERPNext: Access your site through the browser and verify:

• Login works
• Dashboard loads correctly
• Module access is normal
• No JavaScript errors in browser console

Step 9: Test Critical Functions

Run through your testing checklist:

Financial Operations:

• Create a sales invoice
• Create a purchase invoice
• Record a payment entry
• Generate financial statements
• Test customizable financial reports

Inventory Operations:

• Create a stock entry
• Process a delivery note
• Test stock reservation (new feature)
• Verify stock balance reports

Manufacturing Operations:

• Create a work order
• Test inward subcontracting (new feature)
• Run MRP
• Check BOM functionality

User Interface:

• Test redesigned workspace
• Verify list view enhancements
• Check role-based field masking
• Test custom scripts and workflows

Integrations:

• Test API connections
• Verify webhook functionality
• Check third-party app integrations
• Test email notifications

Reports:

• Run standard reports
• Test custom reports
• Verify report performance
• Check print formats

Step 10: Monitor for Issues

Watch for problems in the first 24-48 hours:

• User-reported issues
• Error logs
• Performance degradation
• Data inconsistencies

Check error logs:

bench –site [your-site-name] logs

Monitor system resources:

htop  # CPU and memory usage
df -h  # Disk space

Post-Upgrade Optimization

After a successful upgrade, optimize your v16 installation for best performance.

1. Rebuild Search Index

bench –site [your-site-name] build-search-index

This improves search performance across ERPNext.

2. Optimize Database

bench –site [your-site-name] mariadb

Then run:

OPTIMIZE TABLE `tabSales Invoice`;
OPTIMIZE TABLE `tabPurchase Invoice`;
OPTIMIZE TABLE `tabStock Ledger Entry`;
— Repeat for other large tables

3. Configure New Features

Set up customizable financial statements:

• Navigate to Accounting > Setup > Financial Statements
• Customize your balance sheet layout
• Configure P&L statement structure
• Test with sample data

Enable stock reservation:

• Go to Stock Settings
• Enable “Allow Stock Reservation”
• Configure reservation rules

Configure role-based field masking:

• Review sensitive fields
• Set up masking rules
• Test with different user roles

4. Update User Training

Train users on new features:

• Redesigned workspace navigation
• Enhanced list view capabilities
• New financial reporting options
• Manufacturing improvements

Create internal documentation:

• Quick reference guides
• Video tutorials
• FAQ document
• Support contact information

Troubleshooting Common Upgrade Issues

If any issue requires expert intervention, reach out to our ERPNext support services team. Even with careful planning, issues can occur. Here’s how to handle common problems.

Issue 1: Migration Fails with Database Errors

Symptoms: Migration stops with SQL errors

Solutions:

1. Check database integrity:

bench –site [your-site-name] mariadb
CHECK TABLE `tabSales Invoice`;

2. Repair corrupted tables:

REPAIR TABLE `tabSales Invoice`;

3. If repair fails, restore from backup and contact support

Issue 2: Custom App Compatibility Problems

Symptoms: Errors after upgrading custom apps

Solutions:

1. Check app logs for specific errors
2. Contact app developer for v16-compatible version
3. Temporarily disable problematic app:

bench –site [your-site-name] uninstall-app [app-name]

4. Complete upgrade, then reinstall updated app

Issue 3: Performance Degradation

Symptoms: ERPNext v16 runs slower than v15

Solutions:

1. Rebuild search index (see above)
2. Clear all caches
3. Optimize database tables
4. Check server resources (may need more RAM)
5. Review custom scripts for inefficiencies

Issue 4: Missing Customizations

Symptoms: Custom fields or scripts disappeared

Solutions:

1. Check if customizations are still in database:

bench –site [your-site-name] console

Then:

frappe.get_all(“Custom Field”, filters={“dt”: “Sales Invoice”})

2. Re-apply customizations if needed
3. Restore from backup if critical customizations are lost

Issue 5: Login Problems

Symptoms: Users can’t log in after upgrade

Solutions:

1. Clear browser cache completely
2. Clear site cache:

bench –site [your-site-name] clear-cache

3. Reset user passwords if needed
4. Check for session-related errors in logs

When to Hire Professional Help

Some upgrade scenarios require expert assistance:

Complex Scenarios That Need Experts:

• Heavy customization: 20+ custom DocTypes, extensive custom code
• Multiple custom apps: Especially if developers are unavailable
• Large databases: >50GB with millions of transactions
• Multi-site deployments: Multiple companies or locations
• Critical business operations: Zero-downtime requirements
• Limited technical expertise: No in-house Linux/Python skills
• Tight timelines: Must complete upgrade quickly
• Previous upgrade failures: Already attempted and failed

What Professional Services Include:

Pre-Upgrade Assessment:

• Infrastructure review
• Custom app compatibility audit
• Risk assessment
• Timeline estimation

Upgrade Execution:

• Staging environment setup
• Complete backup management
• Upgrade execution
• Testing and verification

Post-Upgrade Support:

• Performance optimization
• User training
• Issue resolution
• Documentation

TCB Infotech ERPNext v16 Upgrade Services:

At TCB Infotech, we’ve successfully upgraded 50+ ERPNext installations with zero data loss and minimal downtime. Our upgrade service includes:

• Comprehensive pre-upgrade audit
• Staging environment testing
• Custom app compatibility fixes
• Database migration with verification
• Post-upgrade optimization
• 30-day post-upgrade support

We handle upgrades for businesses of all sizes, from small deployments to enterprise multi-site installations.

If you need expert help beyond upgrades, explore our full range of ERPNext implementation services.

Contact us for a free upgrade assessment: Discuss your specific situation, get a timeline estimate, and receive a detailed upgrade plan.

Rollback Plan: If Things Go Wrong

Despite best efforts, sometimes you need to rollback.

When to Rollback:

• Critical functionality is broken
• Data integrity issues discovered
• Performance is unacceptably degraded
• Custom apps won’t work and can’t be fixed quickly

Rollback Process:

1. Stop bench:

bench –site [your-site-name] set-maintenance-mode on

2. Switch back to v15:

bench switch-to-branch version-15 frappe –upgrade
bench switch-to-branch version-15 erpnext –upgrade
bench setup requirements
bench build

3. Restore database from backup:

bench –site [your-site-name] restore /path/to/v15-backup.sql.gz

4. Clear cache and restart:

bench –site [your-site-name] clear-cache
bench restart
bench –site [your-site-name] set-maintenance-mode off

5. Verify rollback:

• Check version
• Test critical functions
• Verify data integrity

Upgrade Timeline: What to Expect

Here’s a realistic timeline for a typical medium-sized deployment:

Week 1-2: Planning Phase

• Review requirements
• Audit customizations
• Set up staging environment
• Create backup strategy

Week 3: Staging Testing

• Perform upgrade in staging
• Test all functionality
• Identify issues
• Fix compatibility problems

Week 4: Production Preparation

• Schedule downtime
• Notify users
• Final backup verification
• Prepare rollback plan

Upgrade Day:

• Hour 0-1: Final backups, pre-upgrade checks
• Hour 1-3: Execute upgrade (switch branches, migrate)
• Hour 3-4: Testing and verification
• Hour 4-6: User acceptance testing
• Hour 6+: Monitor and support

Week After Upgrade:

• Daily monitoring
• User support
• Performance optimization
• Issue resolution

Frequently Asked Questions

Q1: Can I skip from v14 directly to v16?

A: It’s not recommended. Upgrade to v15 first, verify everything works, then upgrade to v16. Skipping versions increases risk of migration failures and data issues.

Q2: How long will the upgrade take?

A: It varies based on database size, customizations, and server performance:

• Small deployment: 2-4 hours
• Medium deployment: 4-8 hours
• Large deployment: 8-24 hours

Always plan for 2-3x your estimate.

Q3: Will my users need retraining?

A: Minimal retraining needed. The redesigned workspace is intuitive, and core workflows remain the same. Plan for 30-60 minutes of orientation on new features.

Q4: Can I upgrade during business hours?

A: Not recommended. Schedule upgrades during off-hours or weekends to minimize disruption. Plan for 4-8 hours of downtime.

Q5: What if my custom app isn’t v16-compatible yet?

A: Contact the app developer for a timeline. If it’s critical and won’t be ready soon, delay your upgrade or hire a developer to update the app.

Q6: Do I need to upgrade if v15 works fine?

A: Not immediately, but plan to upgrade within 6-12 months. ERPNext v15 will eventually stop receiving updates, and v16’s performance improvements are significant.

Q7: Can I test v16 without affecting production?

A: Yes. Set up a staging environment by restoring a production backup to a test server. This is strongly recommended.

Q8: What happens to my data during upgrade?

A: Your data is migrated to the new schema. Nothing is deleted, but data structures may change. Always backup first.

Conclusion: Upgrade with Confidence

When you upgrade ERPNext version 15 to 16, you unlock major improvements in performance, usability, and governance. Upgrading to ERPNext v16 brings substantial benefits: 2x performance, powerful new features, and improved user experience. With proper planning, thorough testing, and careful execution, you can upgrade smoothly with minimal disruption.

Key takeaways:

• Plan thoroughly: Complete the pre-upgrade checklist
• Test in staging: Never upgrade production directly
• Backup everything: Multiple times, multiple locations
• Allow adequate time: Don’t rush the process
• Monitor closely: Watch for issues in the first week
• Get help if needed: Complex upgrades benefit from expert assistance

Whether you’re upgrading yourself or working with an ERPNext implementation partner like TCB Infotech, following this guide ensures a successful transition to ERPNext v16. If you plan to upgrade ERPNext version 15 to 16, prepare staging early to avoid errors.

Still evaluating ERP platforms? Read our detailed ERPNext vs Odoo comparison to make an informed decision.

Ready to upgrade? Start with your staging environment today, and experience the power of ERPNext version 16.

Need help with your ERPNext v16 upgrade? TCB Infotech specializes in smooth, zero-data-loss ERPNext upgrades. Contact us for a free consultation and upgrade assessment.