Authentication

Authenticate Pixi with private conda channels and PyPI registries

Pixi supports authentication with various package repositories including prefix.dev, private Quetz instances, anaconda.org, and PyPI registries.

Authentication Methods

Pixi supports multiple authentication methods:

• Bearer Token - Used by prefix.dev
• Conda Token - Used by anaconda.org and Quetz
• Basic HTTP Auth - Username and password
• S3 Credentials - For S3-based channels
• Keyring - For PyPI registries

Conda Channel Authentication

Command Syntax

pixi auth login [OPTIONS] <HOST>

Arguments:
  <HOST>  The host to authenticate with (e.g. repo.prefix.dev)

Options:
  --token <TOKEN>                            Bearer token (prefix.dev)
  --username <USERNAME>                      Basic HTTP auth username
  --password <PASSWORD>                      Basic HTTP auth password
  --conda-token <CONDA_TOKEN>                Anaconda.org/Quetz token
  --s3-access-key-id <S3_ACCESS_KEY_ID>      S3 access key ID
  --s3-secret-access-key <SECRET_KEY>        S3 secret access key
  --s3-session-token <SESSION_TOKEN>         S3 session token

Authentication Examples

prefix.dev

pixi auth login prefix.dev --token pfx_jj8WDzvnuTHEGdAhwRZMC1Ag8gSto8

S3 authentication also supports AWS’s standard AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. See the S3 section for details.

Authentication Types Explained

Bearer Token

Standard token authentication used by prefix.dev. The token is sent with every request in the Authorization header:

Authorization: Bearer <TOKEN>

Conda Token

Used by anaconda.org and Quetz servers. The token is encoded in the URL:

https://conda.anaconda.org/t/<TOKEN>/conda-forge/linux-64/...

Basic HTTP Authentication

Username and password authentication, commonly used with self-hosted servers:

http://user:[e-mail]/...

Easily configured with reverse proxies like Nginx or Apache.

Credential Storage

Platform-Specific Storage

Pixi stores credentials securely using your system’s keychain:

Windows

Location: Credentials Manager
Search for: "rattler"
Access: Windows Credentials Manager app

Fallback Storage

On servers without keychain support, Pixi stores credentials in an insecure JSON file:

~/.rattler/credentials.json

This fallback storage is unencrypted. Use environment-based authentication in production environments.

Override Authentication Storage

Use the RATTLER_AUTH_FILE environment variable to specify a custom credentials file:

export RATTLER_AUTH_FILE=$HOME/credentials.json
pixi install

# Or specify per-command
pixi global install --auth-file $HOME/credentials.json package-name

RATTLER_AUTH_FILE takes precedence over the CLI --auth-file argument.

Credentials File Format

The JSON file should follow this format:

credentials.json

{
  "*.prefix.dev": {
    "BearerToken": "your_token"
  },
  "otherhost.com": {
    "BasicHTTP": {
      "username": "your_username",
      "password": "your_password"
    }
  },
  "conda.anaconda.org": {
    "CondaToken": "your_token"
  },
  "s3://my-bucket": {
    "S3Credentials": {
      "access_key_id": "my-access-key-id",
      "secret_access_key": "my-secret-access-key",
      "session_token": null
    }
  }
}

Wildcard hosts (e.g., *.prefix.dev) match any subdomain like repo.prefix.dev.

You can also configure the authentication file in the global configuration file.

PyPI Authentication

Pixi supports two methods for PyPI authentication:

1. Keyring authentication
2. .netrc file authentication

Keyring Authentication

Pixi uses the Python keyring library for PyPI authentication.

1. Install Keyring

   Install keyring globally based on your registry type:

   Basic Auth

   pixi global install keyring
   
2. Configure Credentials

   Store credentials and configure your workspace:

   Basic Auth

   # Store credentials
   keyring set https://my-index/simple your_username
   # Password prompt will appear
   
   # Configure pixi.toml
   # Add your_username@ to the registry URL
   
3. Install with Keyring

   Enable keyring provider when installing:

   pixi install --pypi-keyring-provider subprocess
   

   Or configure globally in your Global Config:

   [pypi-config]
   keyring-provider = "subprocess"
   

.netrc File Authentication

Store PyPI credentials in a .netrc file:

1. Create .netrc file

   Create the file in your home directory:

   Unix/Linux/macOS

   Location: $HOME/.netrc
   
2. Add credentials

   .netrc

   machine registry-name
   login admin
   password admin
   
3. Use custom location (optional)

   Set the NETRC environment variable:

   export NETRC=/my/custom/location/.netrc
   pixi install
   

For more details, see the .netrc file format documentation.

Best Practices

Use Secrets Management

Never commit credentials to version control. Use environment variables or CI/CD secrets.

Rotate Credentials

Regularly rotate authentication tokens and passwords for better security.

Minimal Permissions

Use tokens with minimal required permissions for each use case.

Environment-Specific Auth

Use different credentials for development, staging, and production environments.