> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:pass@example.com`)
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:

```bash theme={null}
# 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
```

<Tip>
  Provide secrets via stdin for security:

  ```bash theme={null}
  echo 'my-password' | uv auth login example.com --password -
  echo 'my-token' | uv auth login example.com --token -
  ```
</Tip>

### Viewing Credentials

Show stored credentials for a URL:

```bash theme={null}
# 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:

```bash theme={null}
uv auth logout example.com
```

<Note>
  Credentials are only removed locally, not invalidated on the remote server.
</Note>

## uv Credentials Store

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

<CodeGroup>
  ```bash Unix theme={null}
  ~/.local/share/uv/credentials/credentials.toml
  ```

  ```bash Windows theme={null}
  %LOCALAPPDATA%\uv\credentials\credentials.toml
  ```
</CodeGroup>

<Warning>
  This file is not intended to be edited manually. Use the `uv auth` commands instead.
</Warning>

### Native Auth Storage (Preview)

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

```bash theme={null}
# 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

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

## netrc Files

[`.netrc`](https://everything.curl.dev/usingcurl/netrc) files are a standard plaintext format for storing credentials.

### Configuration

Create a `.netrc` file in your home directory:

```text ~/.netrc theme={null}
machine example.com
login myusername
password mypassword

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

<ParamField path="machine" type="string" required>
  The hostname of the server.
</ParamField>

<ParamField path="login" type="string" required>
  The username for authentication.
</ParamField>

<ParamField path="password" type="string" required>
  The password or token for authentication.
</ParamField>

### Custom netrc Location

Use the `NETRC` environment variable to specify a custom location:

```bash theme={null}
export NETRC="/path/to/custom/netrc"
uv sync
```

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

## Keyring Providers

Keyring providers allow credential retrieval from external tools compatible with Python's [keyring](https://github.com/jaraco/keyring) package.

### Subprocess Provider

The "subprocess" provider invokes the `keyring` command-line tool:

```bash theme={null}
# Install keyring globally
uv tool install keyring

# Enable keyring provider
export UV_KEYRING_PROVIDER=subprocess
uv sync
```

Or configure it persistently:

```toml pyproject.toml theme={null}
[tool.uv]
keyring-provider = "subprocess"
```

<ParamField path="keyring-provider" type="string">
  Keyring provider to use:

  * `"disabled"`: No keyring (default)
  * `"subprocess"`: Invoke `keyring` CLI
</ParamField>

Command-line usage:

```bash theme={null}
uv sync --keyring-provider subprocess
```

<Warning>
  The `keyring` executable must be in `PATH` (installed globally or in the active environment).
</Warning>

## 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:

```toml pyproject.toml theme={null}
[[tool.uv.index]]
name = "internal-proxy"
url = "https://example.com/simple"
```

```bash theme={null}
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:

```toml pyproject.toml theme={null}
[[tool.uv.index]]
name = "internal"
url = "https://public:koala@pypi-proxy.corp.dev/simple"
```

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

### Authentication Behavior

Control credential discovery behavior per index:

```toml pyproject.toml theme={null}
[[tool.uv.index]]
name = "example"
url = "https://example.com/simple"
authenticate = "always"  # or "auto" (default), "never"
```

<ParamField path="authenticate" type="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
</ParamField>

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

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

## 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:

```toml pyproject.toml theme={null}
[project]
dependencies = [
  "package @ https://username:password@example.com/package.whl"
]
```

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

## Authentication Examples

### Private PyPI Mirror with netrc

```text ~/.netrc theme={null}
machine pypi.company.com
login employee
password secret-token
```

```toml pyproject.toml theme={null}
[[tool.uv.index]]
name = "corporate"
url = "https://pypi.company.com/simple"
default = true
```

### Azure Artifacts with Environment Variables

```toml pyproject.toml theme={null}
[[tool.uv.index]]
name = "azure-artifacts"
url = "https://pkgs.dev.azure.com/org/project/_packaging/feed/pypi/simple/"
```

```bash theme={null}
export UV_INDEX_AZURE_ARTIFACTS_USERNAME=dummy
export UV_INDEX_AZURE_ARTIFACTS_PASSWORD="$AZURE_ARTIFACTS_TOKEN"
uv sync
```

### Google Artifact Registry with Keyring

```bash theme={null}
# 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
```

```toml pyproject.toml theme={null}
[[tool.uv.index]]
name = "private-registry"
url = "https://us-python.pkg.dev/project/repository/simple/"
```

### AWS CodeArtifact with Token

```bash theme={null}
# 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
```

```toml pyproject.toml theme={null}
[[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

```bash theme={null}
# 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
```

```toml pyproject.toml theme={null}
[[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](/concepts/authentication/certificates).

## Third-Party Services

For provider-specific authentication guides:

* [Azure Artifacts](/guides/integration/alternative-indexes#azure-artifacts)
* [Google Artifact Registry](/guides/integration/alternative-indexes#google-artifact-registry)
* [AWS CodeArtifact](/guides/integration/alternative-indexes#aws-codeartifact)

## Related Resources

* [Indexes](/configuration/indexes) - Configure custom package indexes
* [Environment Variables](/configuration/environment-variables) - All UV\_\* variables reference
* [Alternative Indexes Guide](/guides/integration/alternative-indexes) - Provider-specific setup