Package Installation
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:
- command-line options
- environment variables
- 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
.
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.
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 frompip
’s.