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

Tip

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
...

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 and twine.

You can also use the system keyring directly to store your credentials. See the pip 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. It will route you through the authentication flow automatically if it is your first time or the previous token has expired. 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 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 Python to use `.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.

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.

Note

.netrc files only support configuring a single set of credentials per server. This means that if you have multiple repositories, you need to use the same token for all of them. The token must have access to each repository.