Skip to main content
The migrate-env command migrates your bench’s virtual environment to a different Python version, useful when upgrading or changing Python versions.

​
Usage

bench migrate-env PYTHON [--no-backup]

​
Arguments

​
python
string
required
Python executable or version to migrate to (e.g., python3.11, python3.10, /usr/bin/python3.11)

​
Options

​
--no-backup
flag
Skip backing up the existing virtual environment

​
What It Does

The command performs the following steps:
  1. Validates the target Python version exists and is compatible
  2. Backs up the current env directory (unless --no-backup is used)
  3. Creates a new virtual environment with the target Python version
  4. Reinstalls all app dependencies in the new environment
  5. Verifies the migration was successful

​
Examples

​
Migrate to Python 3.11

# Migrate to Python 3.11 (with backup)
cd ~/frappe-bench
bench migrate-env python3.11

​
Migrate to Python 3.10

# Migrate to Python 3.10 (with backup)
bench migrate-env python3.10

​
Migrate Without Backup

# Skip backup (faster, but risky)
bench migrate-env python3.11 --no-backup
Only use --no-backup if you have another backup or are certain the migration will succeed.

​
Use Specific Python Executable

# Use a specific Python installation
bench migrate-env /usr/bin/python3.11

# Use Python from custom location
bench migrate-env /opt/python/3.11/bin/python3

​
Complete Migration Workflow

​
Before Migration

# 1. Check current Python version
cd ~/frappe-bench
./env/bin/python --version

# 2. Backup sites
bench backup-all-sites

# 3. Check disk space (for env backup)
df -h .

​
Perform Migration

# 4. Migrate environment
bench migrate-env python3.11
The command output will show: 
Backing up existing env...
Creating new virtual environment with python3.11...
Reinstalling dependencies...
Migration completed successfully.

​
After Migration

# 5. Verify new Python version
./env/bin/python --version

# 6. Test bench
bench version

# 7. Start bench and test
bench start

​
System Upgrade Example

When upgrading Ubuntu/Debian and Python: 
# 1. Upgrade system
sudo apt update
sudo apt upgrade

# 2. Install new Python version
sudo apt install python3.11 python3.11-dev python3.11-venv

# 3. Verify installation
python3.11 --version

# 4. Migrate each bench
cd ~/frappe-bench
bench migrate-env python3.11

cd ~/production-bench
bench migrate-env python3.11

​
Backup Location

When backup is enabled (default), the old environment is moved to: 
~/frappe-bench/env_backup_TIMESTAMP/
Example: 
~/frappe-bench/env_backup_20260305_143022/

​
Managing Backups

# List environment backups
ls -ld ~/frappe-bench/env_backup_*/

# Check backup size
du -sh ~/frappe-bench/env_backup_*/

# Remove old backups after successful migration
rm -rf ~/frappe-bench/env_backup_*/

​
Rollback Failed Migration

If the migration fails: 
# 1. Remove failed new environment
rm -rf ~/frappe-bench/env

# 2. Restore from backup
mv ~/frappe-bench/env_backup_TIMESTAMP ~/frappe-bench/env

# 3. Test restored environment
bench version

​
Python Version Requirements

  • Minimum: Python 3.10
  • Recommended: Python 3.11
  • Maximum: Python 3.12
  • Minimum: Python 3.7
  • Recommended: Python 3.10
  • Maximum: Python 3.11
  • Minimum: Python 3.6
  • Recommended: Python 3.9
  • Maximum: Python 3.10

​
Implementation Details

Location: bench/commands/utils.py:170 The command:
  1. Validates the Python executable exists
  2. Creates a timestamped backup of the env directory
  3. Removes the old env directory
  4. Creates a new virtual environment using the specified Python
  5. Upgrades pip, setuptools, and wheel
  6. Reinstalls all app requirements from their respective requirements.txt files
  7. Reinstalls bench CLI in editable mode

​
When to Migrate

Migrate your Python environment when:
  • OS Upgrade: After upgrading Ubuntu, Debian, or other OS
  • Python EOL: When your Python version reaches end-of-life
  • Security: To get security fixes in newer Python versions
  • Performance: Newer Python versions often have performance improvements
  • Compatibility: When Frappe requires a newer Python version
  • Development: To test on different Python versions

​
Performance Considerations

Migration time depends on:
  • Number of apps installed
  • Network speed (for downloading packages)
  • CPU speed (for compiling binary packages)
Expect 5-15 minutes for a typical bench.

​
Troubleshooting

If the Python version doesn’t exist:
# Check available Python versions
ls /usr/bin/python*

# Install required version (Ubuntu/Debian)
sudo apt install python3.11 python3.11-dev python3.11-venv

# Try migration again
bench migrate-env python3.11
If packages fail to compile:
# Install development packages (Ubuntu/Debian)
sudo apt install python3-dev python3.11-dev build-essential

# Install system dependencies
sudo apt install libffi-dev libssl-dev libmysqlclient-dev

# Retry migration
bench migrate-env python3.11
If you get permission errors:
# Fix ownership
sudo chown -R $USER:$USER ~/frappe-bench

# Retry migration
bench migrate-env python3.11
If you run out of disk space:
# Check available space
df -h .

# Use --no-backup to skip backup
bench migrate-env python3.11 --no-backup

# Or clean up first
sudo apt autoremove
sudo apt clean
rm -rf ~/frappe-bench/env_backup_*/

​
Best Practices

Test the migration on a development bench before production:
# Clone production bench
cd ~
cp -r production-bench test-bench

# Test migration
cd test-bench
bench migrate-env python3.11
bench start
Always backup before migration:
# Backup sites
bench backup-all-sites

# Backup entire bench
cd ~
tar -czf frappe-bench-backup.tar.gz frappe-bench/

# Then migrate (with env backup)
cd frappe-bench
bench migrate-env python3.11
For production:
  • Schedule during low-traffic periods
  • Notify users of maintenance
  • Have rollback plan ready
  • Monitor after migration
After confirming migration worked:
# Remove environment backup
rm -rf ~/frappe-bench/env_backup_*/

# Update cron jobs if needed
crontab -e

Build docs developers (and LLMs) love

Get started for freeTalk to us