Skip to content

Resolving conflicts with user-installed Jupyter packages

JupyterHub provides centrally managed versions of JupyterLab and Notebook. Packages previously installed in your persistent home directory can override these versions and cause compatibility problems.

Does your JupyterHub server fail to start?

If your regular server still starts, follow the instructions on this page using a terminal.

If the server is starting or fails to start:

  1. Open the Log Viewer and check the server logs for error messages.
  2. If the error is caused by packages or configuration files in your home directory, start Rescue Mode.
  3. Use rescue mode to back up, rename, or repair the conflicting files as described below.

If you contact support, include the relevant error messages, but do not include passwords, tokens, cookies, or other sensitive information.

This often happens after using:

python -m pip install --user ...

Possible symptoms

  • JupyterLab extension compatibility warnings
  • Missing or broken launcher entries
  • Different behavior for existing and new users
  • Packages loaded from ~/.local instead of /opt/conda

Check the package locations

Open a terminal and run:

python - <<'PY'
import jupyterlab
import notebook

print("JupyterLab:", jupyterlab.__version__, jupyterlab.__file__)
print("Notebook:", notebook.__version__, notebook.__file__)
PY

Packages managed by the JupyterHub image should normally be loaded from:

/opt/conda/lib/pythonX.Y/site-packages/

A path below the following directory indicates a user-installed package:

~/.local/lib/pythonX.Y/site-packages/

Test without user-installed packages

Run:

PYTHONNOUSERSITE=1 jupyter labextension list

If the warnings disappear, packages in your home directory are probably overriding the image packages.

Fix the problem

If your regular JupyterHub server starts, run the following commands from a JupyterHub terminal.

If the server does not start, first check the Log Viewer. If the logs indicate that user-installed packages or files in your home directory are causing the failure, start Rescue Mode and run the repair commands there.

First determine your Python version:

python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")'

For Python 3.12, back up the user-installed packages with:

mv ~/.local/lib/python3.12/site-packages \
   ~/.local/lib/python3.12/site-packages.backup-$(date +%Y%m%d-%H%M%S)

Also back up user-installed JupyterLab extensions:

if [ -d ~/.local/share/jupyter/labextensions ]; then
    mv ~/.local/share/jupyter/labextensions \
       ~/.local/share/jupyter/labextensions.backup-$(date +%Y%m%d-%H%M%S)
fi

These commands rename the directories instead of deleting them.

Afterwards:

  1. Save your work.
  2. Stop your JupyterHub server.
  3. Start the server again.
  4. Reload JupyterLab.

Verify the result

Run the package-location check again. JupyterLab and Notebook should now be loaded from /opt/conda.

You can also check the extensions:

jupyter labextension list
jupyter server extension list

Avoid future conflicts

Do not install or upgrade core Jupyter packages with pip install --user, particularly:

  • jupyterlab
  • notebook
  • jupyter-server
  • jupyter-server-proxy
  • jupyterhub

For additional project packages, use a virtual environment or Conda environment instead.

Support

If the problem remains, contact the JupyterHub support team and include the output of:

python -m site
python -m pip list --user
jupyter labextension list

Do not include passwords, tokens, cookies, or other sensitive information.