Package Installation

Workbench

This section focuses on pip and uv for installing Python packages across all session types. Other tools may 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

Sessions can be configured to use Posit Public Package Manager (3PM), or any other private or public Python package index, as the default Python package index for both pip and uv. This can be configured by setting session-python-index-url in rserver.conf. The default rserver.conf file included with new Workbench installs sets this value to 3PM:

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

The value set by session-python-index-url is added to the session via the environment variables PIP_INDEX_URL and UV_INDEX_URL and automatically used by pip and uv. See the following sections on this page for more information on how those environment variables interact with pip and uv’s configuration files, as well as how to set other configuration items for sessions.

Configuring additional pip and uv settings

Generally, pip and uv can be configured via three main methods:

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

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

For example, as mentioned above, setting the session-python-index-url configuration item in rserver.conf automatically sets PIP_INDEX_URL and UV_INDEX_URL in the session environment. These environment variables override any index-url value set in /etc/pip.conf. Additionally, if a user wants to override the values set in /etc/pip.conf as well as PIP_INDEX_URL, they may do so by passing --index-url example.index.site directly to pip.

Important

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

Configuration using configuration files

Admins can configure global pip and uv settings for all sessions using /etc/pip.conf or /etc/uv/uv.toml, respectively. However, it’s important to note that Workbench adds environment variables into sessions in order to set convenient pip or uv settings. To ensure your configuration isn’t silently overriden by environment variables, configure pip and uv using environment variables as described in the section below.

Configuration using environment variables

You can always configure pip or uv using configuration files, but, because Workbench uses environment variables to set convenient defaults in sessions, setting other configuration items with environment variables will provide more consistent behavior. This can be done with a high degree of granularity by using the launcher-env configuration file. For information on which configuration items each tool exposes via environment variables see pip’s configuration environment variables or uv’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 like session-python-index-url, for example, which sets PIP_INDEX_URL and UV_INDEX_URL in session environments.

If you have a Python package repository for your own Python packages, such as Posit Package Manager, or have a PyPI mirror inside your firewall, you can configure Posit Workbench to use that package repository when installing packages via pip or uv.

For example, to configure your own custum primary and backup Python package repository for Positron sessions, and add a timeout of 60 seconds to all sessions, add the following to /etc/rstudio/launcher-env:

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

JobType: session
5Workbench: any
6Environment: PIP_TIMEOUT=60
7 UV_HTTP_TIMEOUT=60
1
Limit these environment variables to sessions (as opposed to adhoc Workbench jobs).
2
Add these environment variables to Positron sessions. (Only one session type per entry. To add these variables to VS Code sessions, for example, create an identical entry but 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 timeout to 60 seconds.
7
Note that uv’s timeout variable name is different from pip’s.
Back to top