Configuring Python Environments

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

pip

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.

uv

uv is a fast Python package installer and resolver. To configure uv to use a Package Manager repository, add the following to your ~/.config/uv/uv.toml file (or /etc/uv/uv.toml for system-wide configuration), replacing 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 may 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.

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 PIP_INDEX_URL="https://packagemanager.posit.co/pypi/latest/simple"
export UV_INDEX_URL="https://packagemanager.posit.co/pypi/latest/simple"

These environment variables are automatically used by both pip and uv.

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 an SSO provider or with an API token using a .netrc file for credentials.

These methods provide a secure way to access authenticated repositories in Python. They can be used with various tools, including pip, uv, and twine.

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

Using Single Sign-On (SSO)

If your server has been configured with an OpenIDConnect provider, then this method is the easiest to use. The posit-keyring package is available on PyPI to make authenticating through SSO and storing credentials a seamless experience.

Inside your virtual environment, you can install the package.

Terminal

pip install posit-keyring

Once posit-keyring is installed, you can configure the environment variables necessary to use the custom keyring backend.

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/"

Now you are able to download packages from the authenticated repository with pip:

Terminal

pip install shiny

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

Now you are able to download packages from the authenticated repository with uv:

Terminal

uv pip install shiny

The first time you install a package (with either pip or uv), it will route you through the authentication flow automatically. If it is your first time or the previous token has expired, you will be prompted to authenticate. The credentials will be stored at ~/.ppm/tokens.toml to be used in 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 more in-depth information on configuration and troubleshooting, read the posit-keyring documentation for more information.

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 pip and uv to use `.netrc`

Both pip and uv 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 should 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 the credentials are stored 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 should 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 the credentials are stored 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 should be 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 should 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.