python: upgrade env instructions

software/python.rst

@@ -154,9 +154,38 @@ directly. It is much more convenient to use the wrapper functions though.
 
 .. important::
 
-   To use the virtualenvwrapper convenience functions (workon etc) in a torque job file you need to add one of the following lines to your job definitions:
+   To use the virtualenvwrapper convenience functions (workon etc) in a torque
+   job file you need to add one of the following lines to your job definitions:
    :file:`source /etc/bash_completion` **or** :file:`module load virtualenvwrapper`
 
+**Upgrade a virtual environment**
+
+If you intend to upgrade the python version in a virtualenv from 3.X to 3.Y you
+will have to rebuild the virtualenv and install new packages, similar to
+R major version upgrades. The process looks something like this:
+
+
+.. code-block:: bash
+
+    # 1. activate the old environment
+    workon ENVNAME
+    # 2. freeze the environment / packages with version
+    pip freeze > env.txt
+    # 3. verify env.txt makes sense
+    cat env.txt
+    # 4. leave the environment
+    deactivate
+    # 5. remove it
+    rmvirtualenv ENVNAME
+    # 6. switch to your desired python version
+    module load python/3.7
+    # 7. rebuild the environment with the new python
+    mkvirtualenv -p $(which python3) ENVNAME
+    # 8. reinstall all packages from the freeze file
+    pip install -r env.txt
+    # 9. inspect version incompatibilities, some old packages might not work/build with your new python
+    diff env.txt <(pip freeze)
+
 
 Conda
 -----