Jupyter Troubleshooting

Workbench

Launcher verification tool

If you experience issues related to running Jupyter sessions, you can use the Launcher verification tool which will attempt to launch both RStudio Pro and Jupyter launcher sessions and provide diagnostic output about what could be going wrong. For more information, see the Troubleshooting section for the Job Launcher integration documentation.

Jupyter fails to launch due to a restrictive umask

A common cause of Jupyter failing to launch is missing permissions due to an overly restrictive umask during installation. For example, if umask is set to 0077, packages added to site-packages during the Python installation are inaccessible within user sessions. Update the permissions of affected files and directories using chmod -R og+rX. This allows all users and groups to read the files, search inside the directories, and run any programs that already have the execute permission set.

Enabling session diagnostics

When the Jupyter session is starting, but not operating properly or efficiently, session diagnostics for an individual user’s session can be helpful for isolating the problem and communicating with Posit Support. The diagnostics include debug logging for the session, environment variables and command line arguments used for starting the session, and optionally may include system call tracing using the Linux utility strace.

To enable diagnostics for a given session user, in the user’s home directory, create a text file with the path: ~/.config/pwb/jupyter-diagnostics and put either the word ‘debug’ or ‘strace’ in the file. For example, run these commands to enable strace diagnostics for the current user:

mkdir -p ~/.config/pwb
echo "strace" > ~/.config/pwb/jupyter-diagnostics

The next Jupyter session started by that user will run with the command line argument: --Session.debug=True and collect additional diagnostic logs. To see the debug logs, look at the session’s output from the Posit Workbench homepage by clicking on the session’s Info -> Details pane.

The additional diagnostics are collected in the directory: ~/.local/share/pwb/log:

  • jupyter-session.log: contains the environment of the last session started
  • jupyter-session.log.strace: if using strace mode, will contain the system call trace of the last session started

pip install fails with error: externally-managed-environment

When end users run pip install <package> against a Python environment installed by uv, the command fails with:

error: externally-managed-environment

× This environment is externally managed
╰─> This Python installation is managed by uv and should not be modified.

This happens because uv writes a PEP 668 EXTERNALLY-MANAGED marker into the Python installation, which causes pip to refuse any install against that interpreter (including a user install to ~/.local).

To allow user-mode pip install in sessions, set PIP_BREAK_SYSTEM_PACKAGES=1 in the session environment by adding the following to /etc/rstudio/launcher-env:

/etc/rstudio/launcher-env
JobType: session
Environment: PIP_BREAK_SYSTEM_PACKAGES=1

For more information on this setting, see Allowing pip install in sessions with an externally-managed Python.

Back to top