Skip to main content
Pixi supports multiple authentication methods for accessing private conda channels and PyPI registries.

​
Authentication Storage

By default, pixi uses the system keyring to store credentials securely. If no keyring is available, credentials fall back to file storage.

​
Default Authentication Sources

  1. System Keyring (preferred)
  2. File storage at ~/.rattler/credentials.json
  3. .netrc file authentication

​
Override Authentication File

Force pixi to use a specific JSON file for authentication instead of the keyring.
​
authentication-override-file
string
Path to authentication JSON file
authentication-override-file = "/path/to/credentials.json"
Or via environment variable: 
export RATTLER_AUTH_FILE="/path/to/credentials.json"

​
Authentication File Format

The credentials file uses JSON format: 
{
  "*.prefix.dev": {
    "BearerToken": "your-token-here"
  },
  "conda.anaconda.org": {
    "BasicHTTP": {
      "username": "user",
      "password": "pass"
    }
  },
  "pypi.company.com": {
    "BearerToken": "pypi-token"
  }
}

​
Authentication Methods

​
Bearer Token Authentication

Used for token-based authentication with conda channels and PyPI. 
{
  "*.prefix.dev": {
    "BearerToken": "pfx_xxxxxxxxxxxxx"
  }
}

​
Basic HTTP Authentication

Username and password authentication for conda channels. 
{
  "conda.anaconda.org": {
    "BasicHTTP": {
      "username": "myuser",
      "password": "mypassword"
    }
  }
}

​
Conda Token Authentication

Anaconda.org-style token authentication. 
{
  "anaconda.org": {
    "CondaToken": "your-conda-token"
  }
}

​
TLS Configuration

​
tls-no-verify

Disable TLS certificate verification for all connections.
​
tls-no-verify
boolean
default:"false"
When true, disables TLS verification for conda and PyPI
tls-no-verify = true
Or via CLI: 
pixi install --tls-no-verify
This is a security risk. Only use for testing or internal networks. For PyPI-specific needs, use pypi-config.allow-insecure-host instead.

​
PyPI Implementation Details

Since uv doesn’t support global TLS verification disable, pixi automatically adds all configured PyPI index hosts to the trusted hosts list when tls-no-verify is enabled. For the main PyPI index, files.pythonhosted.org is also added.
Important limitation: If your custom PyPI index redirects downloads to a different host (e.g., CDN), that download host is not automatically trusted. You must manually add it to pypi-config.allow-insecure-host.

​
tls-root-certs

Control which TLS root certificates are used for HTTPS connections.
​
tls-root-certs
enum
default:"webpki"
Available options:
  • webpki: Bundled Mozilla root certificates (most portable)
  • native: System certificate store (required for corporate CAs)
  • all: Both bundled and system certificates
tls-root-certs = "native"
Or via CLI: 
pixi install --tls-root-certs native
Or via environment variable: 
export PIXI_TLS_ROOT_CERTS=native
This setting only affects rustls-tls builds (standalone binaries from GitHub releases). For native-tls builds (conda-forge packages), the system’s TLS library always uses system certificates.

​
Using CLI Authentication Commands

Pixi provides CLI commands to manage authentication: 
# Login to a conda channel
pixi auth login conda.anaconda.org --token your-token

# Login with username/password
pixi auth login conda.anaconda.org --username user --password pass

# Logout from a channel
pixi auth logout conda.anaconda.org

​
Environment Variables

​
RATTLER_AUTH_FILE

Overrides the default authentication file location. 
export RATTLER_AUTH_FILE="/secure/path/credentials.json"
pixi install
When set, this is the only source of authentication data used by pixi.

​
Best Practices

​
Security Recommendations

  1. Use system keyring when available for maximum security
  2. Restrict file permissions for credential files: 
    chmod 600 ~/.rattler/credentials.json
  3. Use environment-specific tokens rather than sharing credentials
  4. Rotate tokens regularly for production systems
  5. Never commit credentials to version control

​
Corporate Environments

For corporate networks with custom CA certificates: 
tls-root-certs = "native"  # or "all"
This ensures pixi trusts your organization’s certificate authority.

​
CI/CD Pipelines

For automated environments: 
# Set credentials via environment variable
export RATTLER_AUTH_FILE="/workspace/credentials.json"

# Or use inline authentication in channel URLs
pixi install --channel "https://token:$TOKEN@conda.company.com/channel"

​
Troubleshooting

​
Authentication Not Working

  1. Check credential format in JSON file
  2. Verify file permissions (should be readable)
  3. Ensure URL pattern matches your channel URL
  4. Use pixi info -vvv to see authentication attempts

​
TLS Certificate Errors

  1. For corporate CAs: Use tls-root-certs = "native"
  2. For self-signed certs: Add to pypi-config.allow-insecure-host
  3. As last resort: Use tls-no-verify = true (not recommended)

​
Keyring Access Issues

If keyring is unavailable or failing: 
authentication-override-file = "~/.rattler/credentials.json"
This forces file-based authentication.