Package installation

Workbench

This section focuses on uv (the recommended Python package installer) and pip (an alternative) for installing Python packages across all session types. Other tools might follow similar configuration patterns.

For session-specific Python package features and configuration, see the Python package installation page for each session type.

Setting a Python package index for sessions

You can configure sessions to use Posit Public Package Manager (P3M), or any other Python package index, as the default index for both uv and pip. Set session-python-index-url in rserver.conf to configure this. The default rserver.conf file included with new Posit Workbench installs sets this value to P3M:

/etc/rstudio/rserver.conf
session-python-index-url=https://packagemanager.posit.co/pypi/latest/simple

session-python-index-url sets the environment variables UV_INDEX_URL and PIP_INDEX_URL in each session. uv and pip use these variables automatically. See the following sections for how these environment variables interact with uv and pip configuration files, and how to set other configuration items for sessions.

Configuring additional uv and pip settings

You can configure uv and pip via three main methods:

  1. command-line options
  2. environment variables
  3. configuration files

These configuration methods have a specific precedence order, with command-line options taking the highest precedence and configuration files taking the lowest. See uv’s precedence order or pip’s precedence order.

For example, setting session-python-index-url in rserver.conf automatically sets UV_INDEX_URL and PIP_INDEX_URL in the session environment. These environment variables override any index-url value set in /etc/uv/uv.toml or /etc/pip.conf. To override both the config file and environment variable values, pass --index-url example.index.site directly to uv or pip.

Important

Remember the configuration precedence order when diagnosing uv or pip behavior. These configuration methods can lead to unexpected behavior if you are unaware of them.

Configuration using configuration files

Admins can configure global uv and pip settings for all sessions using /etc/uv/uv.toml or /etc/pip.conf, respectively. Workbench adds environment variables into sessions to set convenient defaults. To prevent environment variables from silently overriding your configuration, configure uv and pip using environment variables as described in the section below.

Configuration using environment variables

You can configure uv or pip using configuration files. However, because Workbench uses environment variables to set session defaults, using environment variables for other configuration items provides more consistent behavior. Use the launcher-env configuration file for granular control. For information on available environment variables, see uv’s configuration environment variables or pip’s configuration environment variables.

Note

The environment variables added in /etc/rstudio/launcher-env take precedence over environment variables set by configuration items in /etc/rserver.conf. For example, session-python-index-url sets UV_INDEX_URL and PIP_INDEX_URL in session environments, but launcher-env values override them.

If you have a private Python package repository, such as Posit Package Manager, or a Python Package Index (PyPI) mirror inside your firewall, configure Workbench to use it. Both uv and pip use the configured repository for package installation.

The following example configures a custom primary and backup Python package repository for Positron sessions and sets a timeout of 60 seconds for all sessions.

/etc/rstudio/launcher-env
1JobType: session
2Workbench: positron
3Environment: UV_INDEX_URL="primary.example.index.site"
 PIP_INDEX_URL="primary.example.index.site"
4 UV_EXTRA_INDEX_URL="backup.example.index.site"
 PIP_EXTRA_INDEX_URL="backup.example.index.site"

JobType: session
5Workbench: any
6Environment: UV_HTTP_TIMEOUT=60
7 PIP_TIMEOUT=60
1
Limit these environment variables to sessions (as opposed to adhoc Workbench jobs).
2
Add these environment variables to Positron sessions. Add only one session type per entry. To add these variables to VS Code sessions, for example, create an identical entry with Workbench: vs code as the session type.
3
Override the default session-python-index-url from /etc/rserver.conf (if set) with your own Python package index.
4
Add an extra, backup package index.
5
Add the timeout environment variables to all session types.
6
Set the uv timeout to 60 seconds.
7
Set the pip timeout to 60 seconds. Note that uv and pip use different environment variable names for the timeout setting.

Allowing pip install in sessions with an externally-managed Python

When a Python environment installed by uv is active in user sessions (for example, on the PATH in Jupyter sessions), pip install commands fail with error: externally-managed-environment. uv writes the Python Enhancement Proposal (PEP) 668 EXTERNALLY-MANAGED marker into the Python installation. This marker causes pip to refuse any install against that interpreter, including a user install to ~/.local.

To let users install packages with pip install from inside sessions, set PIP_BREAK_SYSTEM_PACKAGES=1 in the session environment:

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

Despite the flag’s name, this does not by itself grant write access to the system installation. Instead, it bypasses the externally-managed marker. pip only writes where filesystem permissions allow. Users without write access to the Python installation’s site-packages folder install into ~/.local.

Back to top