Authentication

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:

URL credentials - Embedded in the URL (e.g., https://user:[email protected])
netrc files - Standard .netrc configuration
uv credentials store - Managed via uv auth commands
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:

~/.local/share/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.

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:[email protected]/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:[email protected]/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:

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

Get Started

Core Concepts

Guides

Integrations

Configuration

Authentication

Authentication Sources

The `uv auth` CLI

Logging In

Viewing Credentials

Logging Out

uv Credentials Store

Native Auth Storage (Preview)

netrc Files

Configuration

Custom netrc Location

Keyring Providers

Subprocess Provider

Authentication Context

Index Authentication

Environment Variable Credentials

URL-Embedded Credentials

Authentication Behavior

Credential Persistence

Request-Level Caching

In Project Files

Authentication Examples

Private PyPI Mirror with netrc

Azure Artifacts with Environment Variables

Google Artifact Registry with Keyring

AWS CodeArtifact with Token

Using uv auth for Multiple Indexes

TLS Certificates

Third-Party Services

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

Configuration

​Authentication Sources

​The uv auth CLI

​Logging In

​Viewing Credentials

​Logging Out

​uv Credentials Store

​Native Auth Storage (Preview)

​netrc Files

​Configuration

​Custom netrc Location

​Keyring Providers

​Subprocess Provider

​Authentication Context

​Index Authentication

​Environment Variable Credentials

​URL-Embedded Credentials

​Authentication Behavior

​Credential Persistence

​Request-Level Caching

​In Project Files

​Authentication Examples

​Private PyPI Mirror with netrc

​Azure Artifacts with Environment Variables

​Google Artifact Registry with Keyring

​AWS CodeArtifact with Token

​Using uv auth for Multiple Indexes

​TLS Certificates

​Third-Party Services

​Related Resources

Build docs developers (and LLMs) love

Authentication Sources

The `uv auth` CLI

Logging In

Viewing Credentials

Logging Out

uv Credentials Store

Native Auth Storage (Preview)

netrc Files

Configuration

Custom netrc Location

Keyring Providers

Subprocess Provider

Authentication Context

Index Authentication

Environment Variable Credentials

URL-Embedded Credentials

Authentication Behavior

Credential Persistence

Request-Level Caching

In Project Files

Authentication Examples

Private PyPI Mirror with netrc

Azure Artifacts with Environment Variables

Google Artifact Registry with Keyring

AWS CodeArtifact with Token

Using uv auth for Multiple Indexes

TLS Certificates

Third-Party Services

Related Resources