Configuring Python environments

Once you have obtained the repository URL, configure your environment to use the URL to download and install packages.

uv

uv is the recommended Python package installer and resolver. To configure uv to use a Posit Package Manager repository, add the following to your ~/.config/uv/uv.toml file. For system-wide configuration, use /etc/uv/uv.toml instead. Replace the url with your Package Manager repository URL:

~/.config/uv/uv.toml

[[index]]
url = "https://packagemanager.posit.co/pypi/latest/simple"
default = true

For project-specific configuration, add the following to your pyproject.toml:

pyproject.toml

[[tool.uv.index]]
url = "https://packagemanager.posit.co/pypi/latest/simple"
default = true

For more details on configuring package indexes with uv, see the uv index configuration documentation.

TLS certificates

By default, uv uses its own built-in certificate store rather than the system certificate store. If your Package Manager server uses certificates signed by an internal certificate authority (CA) or self-signed certificates, uv might report an error such as invalid peer certificate: UnknownIssuer.

To configure uv to use the system certificate store, set the UV_NATIVE_TLS environment variable:

Terminal

export UV_NATIVE_TLS=true

Or pass the --native-tls flag:

Terminal

uv pip install --native-tls shiny

For more details, see the uv TLS documentation.

pip

pip is an alternative client for installing Python packages. To configure pip globally for all projects, use the pip config command to set the global.index-url to your repository URL:

Terminal

pip config set global.index-url https://packagemanager.posit.co/pypi/latest/simple

Note

If using virtual environments with venv, activate your virtual environment first, then run the pip config command above to set the Package Manager repository for that specific environment. Refer to Installing packages using pip and virtual environments in the Python documentation for more information.

requirements.txt

To use a Package Manager repository with a specific project defined by a requirements.txt file, add -i [repositoryURL] to the top of your file, for example:

requirements.txt

-i https://packagemanager.posit.co/pypi/latest/simple
pandas
scipy
...

Positron

For Python sessions in Positron, you can configure the package index using environment variables. Add the following to your ~/.bashrc, ~/.zshrc, or Positron environment settings, replacing the URL with your Package Manager repository URL:

~/.bashrc or ~/.zshrc

export UV_INDEX_URL="https://packagemanager.posit.co/pypi/latest/simple"
export PIP_INDEX_URL="https://packagemanager.posit.co/pypi/latest/simple"

Both uv and pip automatically use these environment variables.

If your repository requires authentication, follow the additional steps to configure Python to use authenticated repositories.

If you are using Positron from Posit Workbench, your administrator can configure the package index globally for all users. See Configuring Posit Workbench for more information.

Authenticated repositories

If your Package Manager repository requires authentication, you can configure Python to fetch credentials from a Single Sign-On (SSO) provider or with an API token using a .netrc file.

These methods provide a secure way to access authenticated repositories in Python. You can use these methods with various tools, including uv, pip, and twine.

You can also use the system keyring directly to store your credentials. See the uv documentation or pip documentation for more information.

Using Single Sign-On (SSO)

If your server uses an OpenIDConnect provider, this method is the easiest to use. The posit-keyring package is available on the Python Package Index (PyPI) to authenticate through SSO and store credentials.

Inside your virtual environment, install the package:

Terminal

uv pip install posit-keyring

Once you install posit-keyring, configure the environment variables for the custom keyring backend.

Terminal

export PACKAGEMANAGER_ADDRESS="https://packagemanager.example.com"
export UV_INDEX="https://__token__@packagemanager.example.com/pypi/latest/simple/"
export UV_KEYRING_PROVIDER="subprocess"

Terminal

export PACKAGEMANAGER_ADDRESS="https://packagemanager.example.com"
export UV_INDEX="https://__token__@packagemanager.example.com/pypi/latest/simple/"
export UV_KEYRING_PROVIDER="subprocess"

Terminal

$env:PACKAGEMANAGER_ADDRESS = "https://packagemanager.example.com"
$env:UV_INDEX = "https://__token__@packagemanager.example.com/pypi/latest/simple/"
$env:UV_KEYRING_PROVIDER = "subprocess"

Alternatively, you can configure uv in your ~/.config/uv/uv.toml file:

~/.config/uv/uv.toml

keyring-provider = "subprocess"

[[index]]
url = "https://__token__@packagemanager.example.com/pypi/latest/simple/"
default = true

You can download packages from the authenticated repository with uv:

Terminal

uv pip install shiny

Terminal

export PACKAGEMANAGER_ADDRESS="https://packagemanager.example.com"
export PIP_INDEX_URL="https://__token__@packagemanager.example.com/pypi/latest/simple/"

Terminal

export PACKAGEMANAGER_ADDRESS="https://packagemanager.example.com"
export PIP_INDEX_URL="https://__token__@packagemanager.example.com/pypi/latest/simple/"

Terminal

$env:PACKAGEMANAGER_ADDRESS = "https://packagemanager.example.com"
$env:PIP_INDEX_URL = "https://__token__@packagemanager.example.com/pypi/latest/simple/"

You can download packages from the authenticated repository with pip:

Terminal

pip install shiny

The first time you install a package (with either uv or pip), the tool routes you through the authentication flow automatically. If the previous token has expired, the tool prompts you to authenticate. The tool stores your credentials at ~/.ppm/tokens.toml for subsequent requests.

Terminal

pip install shiny
Looking in indexes: https://****@packagemanager.example.com/pypi/latest/simple/

Please open the following URL in your browser:
  https://org.instance.okta.com/activate?user_code=PQNPQKTK

And enter the following code when prompted:
  PQNPQKTK

Waiting for authorization...
PPM token saved to ~/.ppm/tokens.toml
Collecting shiny
  Downloading https://packagemanager.example.com/pypi/latest/packages/shiny/c7748d0cd32696477613b9c00664320ea1604b9d9770a2ec2e8ea7ea5e0b44b4/shiny-1.4.0-py3-none-any.whl (3.9 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.9/3.9 MB 414.3 MB/s  0:00:00
...

For configuration and troubleshooting details, read the posit-keyring documentation.

Using SSO with uv when a .netrc file exists

uv checks for credentials in .netrc before consulting the keyring. If you have a .netrc file configured for your Package Manager server (for example, for R authentication), uv will use those credentials instead of triggering the SSO flow.

If the .netrc token is valid and has access to your Python repositories, this will work without any issues. However, if the token has expired, uv will report a 401 or 403 error instead of prompting you to reauthenticate through SSO.

To use SSO with uv while keeping your .netrc file for R, set the NETRC environment variable to bypass the .netrc file:

Terminal

# Linux/macOS
export NETRC=/dev/null

# Windows (PowerShell)
$env:NETRC = "NUL"

Using API tokens

Getting a token

Your Package Manager administrator can provide you with a token to use for authentication. See Creating API Tokens for details.

Configure uv and pip to use `.netrc`

Both uv and pip support reading credentials from .netrc files. Create a .netrc file in your home directory with your API token:

Create a .netrc file in your home directory at ~/.netrc.

Add the following content, replacing [packagemanager.example.com] with your Package Manager server address and [your-token] with your actual token.
```
~/.netrc
```
```
machine [packagemanager.example.com]
login __token__
password [your-token]
```
The machine field must not contain a protocol, port, or repository path. If your repository URL is https://packagemanager.example.com/pypi/latest, use packagemanager.example.com for the machine field.
Since this file stores credentials in plaintext, ensure that the ~/.netrc file is only accessible to you by running:
```
Terminal
```
```
chmod 600 ~/.netrc
```

Create a .netrc file in your home directory at ~/.netrc.

Add the following content, replacing [packagemanager.example.com] with your Package Manager server address and [your-token] with your actual token.
```
~/.netrc
```
```
machine [packagemanager.example.com]
login __token__
password [your-token]
```
The machine field must not contain a protocol, port, or repository path. If your repository URL is https://packagemanager.example.com/pypi/latest, use packagemanager.example.com for the machine field.
Since this file stores credentials in plaintext, ensure that the ~/.netrc file is only accessible to you by running:
```
Terminal
```
```
chmod 600 ~/.netrc
```

Create a .netrc file in your home directory at ~/.netrc. On Windows, this location is your Windows user folder (typically C:\Users\[user], where [user] is your Windows username).

Add the following content, replacing [packagemanager.example.com] with your Package Manager server address and [your-token] with your actual token.
```
~/.netrc
```
```
machine [packagemanager.example.com]
login __token__
password [your-token]
```
The machine field must not contain a protocol, port, or repository path. If your repository URL is https://packagemanager.example.com/pypi/latest, use packagemanager.example.com for the machine field.