add guide for uninstalling uenv CLI

docs/software/uenv/index.md

@@ -368,6 +368,7 @@ By default, the modules are not activated when a uenv is started, and need to be
     cmake version 3.30.5
     ```
 
+[](){#ref-uenv-error-v9modules}
 ??? warning "bash: module: command not found"
 
     Version 9.0.0 of uenv, installed on October 22 2025, has a bug that removes the module command on Santis and Clariden.
@@ -532,32 +533,6 @@ it is possible to override the default uenv by passing a different `--uenv`  and
 
 * Note how the second call has access to `mpicc`, provided by `prgenv-gnu`.
 
-[](){#ref-uenv-installation}
-## Installing the uenv tool
-
-The command line tool can be installed from source, if you are working on a cluster that does not have uenv installed, or if you need to test a new version.
-
-!!! note
-    uenv is installed already on CSCS clusters, so installation is not required.
-
-    Only follow these steps if you are advised to test out a new version (e.g. if it has a fix for an issues that you are encountering).
-
-```bash
-git clone https://github.com/eth-cscs/uenv2.git
-cd uenv2
-
-./install-alps-local.sh # (1)!
-
-# update bashrc
-echo "export PATH=\$HOME/.local/\$(uname -m)/bin:\$PATH" >> $HOME/.bashrc 
-echo "unset -f uenv" >> $HOME/.bashrc
-```
-
-1. Run installation script. This will install uenv in `$HOME/.local/$(uname -m)/bin/`.
-
-!!! warning
-    Before uenv can be used, you need to log out then back in again and type `which uenv` to verify that uenv has been installed in your `$HOME` path.
-
 [](){#ref-uenv-labels}
 ## uenv labels
 
@@ -701,3 +676,100 @@ $ myenv
 ```
 
 The benefit of this approach is that you can create multiple environments, whereas modifying `.bashrc` will lock you into using the same environment every time you log in.
+
+[](){#ref-uenv-uninstall}
+## Uninstalling the uenv tool
+
+It is strongly recommended to use the version of uenv installed on the system, instead of installing your own version from source.
+This guide walks through the process of detecting if you have an old version installed, and removing it.
+
+!!! note
+    In the past CSCS has recommended installing a more recent version of uenv to help fix issues for some users.
+    Some users still have old self-installed versions installed in `HOME`, so they are missing out on new uenv features, and possibly seeing errors on systems with the most recent `v9.0.0` uenv installed.
+
+!!! warning "error caused by incompatible uenv version"
+    If trying to use `uenv run` or `uenv start`, and you see an error message like the following:
+
+    ```
+    error: unable to exec '/capstor/scratch/cscs/wombat/.uenv-images/images/61d1f21881a6....squashfs:/user-environment':
+    No such file or directory (errno=2)
+    ```
+
+    Then you are probably using an old version of uenv that is not compatible with the version of `squashfs-mount` installed on the system.
+
+### Detecting which version of uenv is installed
+
+First, log into the target cluster, and enter `type uenv` and inspect the output.
+
+The system version of `uenv` is installed in `/usr/bin`, so if you see the following you do not need to make any changes:
+
+```console
+$ type uenv
+uenv is /usr/bin/uenv
+```
+
+Version 5 of uenv used a bash function called `uenv`, which will give output that looks like this:
+
+```console
+$ type uenv
+uenv is a function
+uenv ()
+{
+    local _last_exitcode=$?;
+    function uenv_usage ()
+    {
+...
+```
+
+If you have installed version 6, 7, 8 or 9, it will be in a different location, for example:
+
+```console
+$ type uenv
+uenv is /users/voldemort/.local/bin/uenv
+```
+
+??? question "why not use `which uenv`?"
+    The `which uenv` command searches the directories listed in the `PATH` environment variable for the `uenv` executable, and ignores bash functions.
+    If there is a `uenv` bash function is set, then it will be take precedence over the `uenv` executable found using `which uenv`.
+
+### Removing version 6 or later
+
+To remove uenv version 6, 7, 8 or 9, delete the executable, then force bash to forget the old command.
+
+```console
+# remove your self-installed executable
+$ rm $(which uenv)
+
+# forget the old uenv command
+$ hash -r
+
+# type and which should point to the same executable in /usr/bin
+$ type uenv
+uenv is /usr/bin/uenv
+$ which uenv
+/usr/bin/uenv
+```
+
+### Removing version 5
+
+To remove version 5, look in your `.bashrc` file for a line like the following and remove or comment it out:
+
+```bash
+# configure the user-environment (uenv) utility
+source /users/voldemort/.local/bin/activate-uenv
+```
+
+Log out and back in again, then issue the following command to force bash to forget the old uenv command:
+```console
+# forget the old uenv command
+$ hash -r
+
+# type and which should point to the same executable in /usr/bin
+$ type uenv
+uenv is /usr/bin/uenv
+$ which uenv
+/usr/bin/uenv
+```
+
+
+

docs/software/uenv/release-notes.md

@@ -29,6 +29,17 @@ This [version](https://github.com/eth-cscs/uenv2/releases/tag/v9.0.0) will repla
 - a bug where the `--only-meta` flag was ignored on `image pull`.
 - add hints to error message when uenv is not found.
 
+[](){#ref-uenv-release-notes-v9.0.0-issues}
+### Known issues
+
+!!! warning "user-installed uenv stopped working"
+    This version introduced changes to the `squashfs-mount` tool used by `uenv start` and `uenv -run` that are incompatible with older versions of uenv.
+    If you see errors that contain `error: unable to exec '...': No such file or directory (errno=2)`, follow the guide for [uninstalling user-installed uenv][ref-uenv-uninstall].
+
+!!! warning "bash: module: command not found"
+    This is a known issue with version 9.0.0 that will be fixed in 9.0.1.
+    See the [uenv modules][ref-uenv-error-v9modules] docs for a workaround.
+
 [](){#ref-uenv-release-notes-v8.1.0}
 ## v8.1.0