ERPNext upgrade from v15 to v16

Take backup to be on safe side

Make sure all apps are clean and do not contain uncommitted changes

 git status

Upgrade pyenv and install Python 3.14

cd ~/.pyenv && git pull && cd -
pyenv install 3.14

Alternatively, use uv to install Python:

uv python install 3.14

Create a new virtual environment with Python 3.14

Move your old env folder to env-archive in case anything goes wrong, so you can return to the original:

cd /opt/bench/frappe-bench/
mv env env-archive

Create a new virtual environment:

uv venv env --python 3.14
source env/bin/activate

Install MariaDB client libraries (downgrade if needed for compatibility)

sudo apt-get install -y \
    libmariadb3=1:10.3.39-0ubuntu0.20.04.2 \
    --allow-downgrades

Then install dev headers:

sudo apt-get install -y \
    libmariadb-dev \
    libmariadb-dev-compat \
    pkg-config \
    python3-dev \
    build-essential

Verify MariaDB config is available:

mysql_config --version

Export MySQL compiler flags so mysqlclient builds correctly

export MYSQLCLIENT_CFLAGS=$(mysql_config --cflags)
export MYSQLCLIENT_LDFLAGS=$(mysql_config --libs)

Install frappe-bench

pip install frappe-bench

Check Node.js version (v24 required for v16)

node --version

Install and set Node.js 24 as default via nvm:

nvm install 24
nvm alias default 24
echo 'nvm use 24 --silent' >> ~/.bashrc
source ~/.bashrc

Upgrade Redis (v6.x or 7.x required)

Add the official Redis repository and install:

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb focal main" \
  | sudo tee /etc/apt/sources.list.d/redis.list

sudo apt-get update
sudo apt-get install -y redis

Verify the version and restart the service:

redis-server --version   # should show 6.x or 7.x
sudo systemctl restart redis

Restart supervisor and confirm Redis is running on the bench port:

sudo supervisorctl restart all
redis-cli -p 13000 info server | grep redis_version

Switch all apps to version-16 branch and upgrade

bench switch-to-branch version-16 frappe --upgrade
bench switch-to-branch version-16 erpnext --upgrade
bench switch-to-branch version-16 hrms --upgrade
bench switch-to-branch version-16 payments --upgrade
bench switch-to-branch version-16 ecommerce_integrations --upgrade
bench switch-to-branch version-16 webshop --upgrade

Run bench update

bench update --reset --no-backup

Get any additional custom apps on the v16 branch

bench get-app offsite_backups --branch version-16
bench get-app blog --branch version-16

Install the new apps on your site

bench --site sitename install-app offsite_backups
bench --site sitename install-app blog

Upgrade SSL

sudo certbot --nginx