Merge pull request #4269 from minrk/document-jupyter-env

Document JUPYTER_PREFER_ENV_PATH=0 for shared user environments

docs/source/reference/config-user-env.md

@@ -57,6 +57,24 @@ The typical locations for these config files are:
 - **system-wide** in `/etc/{jupyter|ipython}`
 - **env-wide** (environment wide) in `{sys.prefix}/etc/{jupyter|ipython}`.
 
+### Jupyter environment configuration priority
+
+When Jupyter runs in an environment (conda or virtualenv), it prefers to load configuration from the environment over each user's own configuration (e.g. in `~/.jupyter`).
+This may cause issues if you use a _shared_ conda environment or virtualenv for users, because e.g. jupyterlab may try to write information like workspaces or settings to the environment instead of the user's own directory.
+This could fail with something like `Permission denied: $PREFIX/etc/jupyter/lab`.
+
+To avoid this issue, set `JUPYTER_PREFER_ENV_PATH=0` in the user environment:
+
+```python
+c.Spawner.environment.update(
+    {
+        "JUPYTER_PREFER_ENV_PATH": "0",
+    }
+)
+```
+
+which tells Jupyter to prefer _user_ configuration paths (e.g. in `~/.jupyter`) to configuration set in the environment.
+
 ### Example: Enable an extension system-wide
 
 For example, to enable the `cython` IPython extension for all of your users, create the file `/etc/ipython/ipython_config.py`: