Authentication

Configure authentication for private indexes using keyring, netrc, credentials store, and tokens

Authentication is required when working with private package indexes and repositories. uv supports multiple authentication methods for HTTP requests.

Authentication Sources

Credentials are retrieved from the following sources, in order of precedence:

1. URL credentials - Embedded in the URL (e.g., https://user:[e-mail])
2. netrc files - Standard .netrc configuration
3. uv credentials store - Managed via uv auth commands
4. Keyring providers - External keyring integration (opt-in)

The uv auth CLI

uv provides a high-level interface for managing credentials.

Logging In

Add credentials for a service:

# Interactive prompt
uv auth login example.com

# With username and password
uv auth login example.com --username myuser --password mypass

# With token (for services using __token__ or arbitrary username)
uv auth login example.com --token mytoken

Provide secrets via stdin for security:

echo 'my-password' | uv auth login example.com --password -
echo 'my-token' | uv auth login example.com --token -

Viewing Credentials

Show stored credentials for a URL:

# Show token for a service
uv auth token example.com

# If username was used during login, provide it
uv auth token --username foo example.com

Logging Out

Remove credentials from local storage:

uv auth logout example.com

Credentials are only removed locally, not invalidated on the remote server.

uv Credentials Store

The uv credentials store persists credentials in a plaintext file located in uv’s state directory:

Unix

~/.local/share/uv/credentials/credentials.toml

%LOCALAPPDATA%\uv\credentials\credentials.toml

This file is not intended to be edited manually. Use the uv auth commands instead.

Native Auth Storage (Preview)

A secure, system-native storage mechanism is available as a preview feature:

# Enable native authentication storage
export UV_PREVIEW_FEATURES=native-auth

When enabled, uv uses the operating system’s native credential storage:

• macOS: Keychain Services
• Windows: Windows Credential Manager
• Linux: DBus-based Secret Service API

Currently, uv only retrieves credentials it has added to the native store. It will not retrieve credentials persisted by other applications.

netrc Files

.netrc files are a standard plaintext format for storing credentials.

Configuration

Create a .netrc file in your home directory:

~/.netrc

machine example.com
login myusername
password mypassword

machine pypi.example.com
login __token__
password pypi-xxxxxxxxxxxxx

machine · string · required

The hostname of the server.

login · string · required

The username for authentication.

password · string · required

The password or token for authentication.

Custom netrc Location

Use the NETRC environment variable to specify a custom location:

export NETRC="/path/to/custom/netrc"
uv sync

Reading credentials from .netrc files is always enabled. If NETRC is not defined, uv falls back to ~/.netrc.

Keyring Providers

Keyring providers allow credential retrieval from external tools compatible with Python’s keyring package.

Subprocess Provider

The “subprocess” provider invokes the keyring command-line tool:

# Install keyring globally
uv tool install keyring

# Enable keyring provider
export UV_KEYRING_PROVIDER=subprocess
uv sync

Or configure it persistently:

pyproject.toml

[tool.uv]
keyring-provider = "subprocess"

keyring-provider · string

Keyring provider to use:

• "disabled": No keyring (default)
• "subprocess": Invoke keyring CLI

Command-line usage:

uv sync --keyring-provider subprocess

The keyring executable must be in PATH (installed globally or in the active environment).

Authentication Context

Authentication applies to hosts specified in:

• [[tool.uv.index]] - Custom package indexes
• --index-url / --extra-index-url - Command-line index URLs
• --find-links - Flat index locations
• package @ https://... - Direct URL dependencies

Index Authentication

Environment Variable Credentials

Provide credentials for named indexes via environment variables:

pyproject.toml

[[tool.uv.index]]
name = "internal-proxy"
url = "https://example.com/simple"

export UV_INDEX_INTERNAL_PROXY_USERNAME=public
export UV_INDEX_INTERNAL_PROXY_PASSWORD=koala
uv sync

Environment variable naming:

• Pattern: UV_INDEX_<NORMALIZED_NAME>_USERNAME and UV_INDEX_<NORMALIZED_NAME>_PASSWORD
• <NORMALIZED_NAME>: Uppercase index name with non-alphanumeric characters replaced by underscores

Examples:

Index Name	Username Variable	Password Variable
internal-proxy	UV_INDEX_INTERNAL_PROXY_USERNAME	UV_INDEX_INTERNAL_PROXY_PASSWORD
my.registry	UV_INDEX_MY_REGISTRY_USERNAME	UV_INDEX_MY_REGISTRY_PASSWORD
azure_artifacts	UV_INDEX_AZURE_ARTIFACTS_USERNAME	UV_INDEX_AZURE_ARTIFACTS_PASSWORD

URL-Embedded Credentials

Embed credentials directly in the index URL:

pyproject.toml

[[tool.uv.index]]
name = "internal"
url = "https://public:[e-mail]/simple"

Credentials are never stored in uv.lock for security. Index credentials must be available at installation time through environment variables, netrc, keyring, or URL.

Authentication Behavior

Control credential discovery behavior per index:

pyproject.toml

[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
authenticate = "always"  # or "auto" (default), "never"

authenticate · string · default: "auto"

Controls when uv searches for credentials:

• "auto": Attempt unauthenticated request first; search for credentials on failure
• "always": Eagerly search for credentials before making requests; error if not found
• "never": Never search for credentials; error if credentials are provided directly

Use "always" when:

• The index forwards unauthenticated requests to public indexes (like GitLab)
• You want to fail fast if credentials are missing

Use "never" when:

• You want to prevent credential leaking
• The index should never use authentication

If a username is set (in URL or environment variable), uv searches for credentials before attempting an unauthenticated request, regardless of the authenticate setting.

Credential Persistence

Request-Level Caching

If authentication is found for an index URL or net location (scheme, host, port), it’s cached for the duration of the command and reused for other queries to that location.

Credentials are not cached across invocations of uv.

In Project Files

When using uv add, uv will not persist index credentials to pyproject.toml or uv.lock (files often included in source control).

Exception: uv will persist credentials for direct URL dependencies:

pyproject.toml

[project]
dependencies = [
  "package @ https://username:[e-mail]/package.whl"
]

If credentials were attached to an index URL during uv add, subsequent operations may fail to fetch dependencies from indexes requiring authentication. Configure persistent authentication using environment variables, netrc, or the uv credentials store.

Authentication Examples

Private PyPI Mirror with netrc

~/.netrc

machine pypi.company.com
login employee
password secret-token

pyproject.toml

[[tool.uv.index]]
name = "corporate"
url = "https://pypi.company.com/simple"
default = true

Azure Artifacts with Environment Variables

pyproject.toml

[[tool.uv.index]]
name = "azure-artifacts"
url = "https://pkgs.dev.azure.com/org/project/_packaging/feed/pypi/simple/"

export UV_INDEX_AZURE_ARTIFACTS_USERNAME=dummy
export UV_INDEX_AZURE_ARTIFACTS_PASSWORD="$AZURE_ARTIFACTS_TOKEN"
uv sync

Google Artifact Registry with Keyring

# Install keyring with Google plugin
uv tool install keyring --with keyrings.google-artifactregistry-auth

# Configure index with keyring
export UV_KEYRING_PROVIDER=subprocess
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken
uv sync

pyproject.toml

[[tool.uv.index]]
name = "private-registry"
url = "https://us-python.pkg.dev/project/repository/simple/"

AWS CodeArtifact with Token

# Generate token
export AWS_CODEARTIFACT_TOKEN=$(aws codeartifact get-authorization-token \
  --domain my-domain \
  --domain-owner 123456789012 \
  --query authorizationToken \
  --output text)

# Use with uv
export UV_INDEX_CODEARTIFACT_USERNAME=aws
export UV_INDEX_CODEARTIFACT_PASSWORD="$AWS_CODEARTIFACT_TOKEN"
uv sync

pyproject.toml

[[tool.uv.index]]
name = "codeartifact"
url = "https://my-domain-123456789012.d.codeartifact.us-east-1.amazonaws.com/pypi/my-repo/simple/"

Using uv auth for Multiple Indexes

# Add credentials for multiple services
echo "$TOKEN1" | uv auth login internal.example.com --token -
echo "$TOKEN2" | uv auth login pypi.company.com --token -

# Use in project
uv sync

pyproject.toml

[[tool.uv.index]]
name = "internal"
url = "https://internal.example.com/simple"

[[tool.uv.index]]
name = "company"
url = "https://pypi.company.com/simple"

TLS Certificates

For custom TLS certificate configuration, see the TLS Certificates documentation.

Third-Party Services

For provider-specific authentication guides:

• Azure Artifacts
• Google Artifact Registry
• AWS CodeArtifact

Related Resources

• Indexes - Configure custom package indexes
• Environment Variables - All UV_* variables reference
• Alternative Indexes Guide - Provider-specific setup