docs(custom-packages): warn against pip --user installs (image shadowing) - #11
Merged
Merged
Conversation
…ing) A pip install run without activating a venv silently falls back to a --user install into ~/.local, which shadows the base image for the whole single-user server. Observed in prod (2026-07-16): a user-site google-cloud-storage lacking the .asyncio submodule the image's gcsfs needs broke the S3 contents manager registration -> file-browser folder tree would not render, object-store folders 404'd; it survived restarts. - Step 5: warning box to always activate the venv first, never pip --user, and to watch for the 'Defaulting to user installation' pip message. - Troubleshooting: new 'A pip user-install broke my environment' entry with detection (ls ~/.local + PYTHONPATH reproduction) and fix (uninstall + restart).
There was a problem hiding this comment.
Pull request overview
This PR strengthens the custom packages user guide by adding explicit guardrails against accidentally doing pip install outside an activated venv (which can default to a persistent ~/.local user-site install that shadows the base image and can break JupyterLab server behavior across restarts).
Changes:
- Adds a prominent Step 5 warning to ensure the venv is activated before installing packages and to stop if pip reports “Defaulting to user installation…”.
- Adds a new troubleshooting entry describing symptoms, how to detect
~/.localshadowing, and how to recover.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+63
to
+64
| > Fix: `pip uninstall --user <package>`, then reinstall inside your activated venv | ||
| > (see [Troubleshooting](#a-pip-user-install-broke-my-environment)). |
Comment on lines
+254
to
+258
| 2. Uninstall the offending user-site package(s) so the base-image version is used | ||
| again (e.g. if you installed `google-cloud-storage`): | ||
| ```bash | ||
| pip uninstall -y google-cloud-storage | ||
| ``` |
| To confirm the shadow is gone (this reproduces the failure a fresh server hits, | ||
| so it should now succeed): | ||
| ```bash | ||
| PYTHONPATH="$(echo ~/.local/lib/python*/site-packages)" python -c "import gcsfs; print('OK')" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A BERDL user's JupyterLab file-browser folder tree stopped rendering (favorites broken, object-store folders 404). Root cause was not the favorites file — it was a
pip install --userpackage in their persistent~/.local(google-cloud-storage 3.4.1, missing the.asynciosubmodule the image'sgcsfsneeds) that shadowed the base image, sojupyter_server_config.pyfailed to register thelakehouse_minioS3 contents manager at startup. Because~/.localis on the persistent home, it survived restarts.The custom-packages guide's venv approach is correct and structurally avoids this — but it never warned users off the trap they actually hit: running
pip installwithout activating the venv, which silently falls back to a--userinstall (Defaulting to user installation because normal site-packages is not writeable).Change
pip install, neverpip install --user, and stop if you see the "Defaulting to user installation" message.ls ~/.local/...+ thePYTHONPATH=~/.local... import gcsfsreproduction), and fix (pip uninstall --user+ Stop/Start).No changes to the recommended workflow itself — just guardrails around the known failure mode.