Global Configuration

Global pixi configuration file reference

Pixi can be configured globally using configuration files. These settings affect all pixi commands and workspaces on your system.

Configuration Locations

Pixi looks for configuration files in multiple locations, loaded in this order (later overrides earlier):

1. System configuration (platform-dependent)
2. Global configuration (user-level)
3. Local configuration (workspace-level)
4. Environment variables
5. CLI arguments

Global Configuration Paths

Linux

~/.config/pixi/config.toml
$XDG_CONFIG_HOME/pixi/config.toml  # If XDG_CONFIG_HOME is set

macOS

~/.config/pixi/config.toml
~/Library/Application Support/pixi/config.toml

Windows

%APPDATA%\pixi\config.toml
C:\Users\<username>\AppData\Roaming\pixi\config.toml

Local Configuration

<workspace-root>/.pixi/config.toml

Configuration Format

Configuration files use TOML format:

# config.toml
default-channels = ["conda-forge", "bioconda"]
tls-no-verify = false

[mirrors]
"https://conda.anaconda.org/conda-forge" = [
  "https://prefix.dev/conda-forge"
]

[pypi-config]
index-url = "https://pypi.org/simple"
extra-index-urls = ["https://my-pypi.example.com/simple"]

[repodata-config]
disable-jlap = false
disable-bzip2 = false
disable-zstd = false

Configuration Options

default-channels

default-channels · array · default: "[\"conda-forge\"]"

Default conda channels to use when channels are not specified in the workspace.

default-channels = ["conda-forge", "bioconda", "pytorch"]

Can also be set via:

pixi config set default-channels '["conda-forge", "bioconda"]'
pixi config append default-channels pytorch
pixi config prepend default-channels my-channel

tls-no-verify

tls-no-verify · boolean · default: "false"

Disable TLS certificate verification. Use with caution!

tls-no-verify = true

Disabling TLS verification is insecure and should only be used for testing or in controlled environments.

authentication-override-file

authentication-override-file · path

Override the default authentication credentials file location.

Default: ~/.rattler/credentials.json

authentication-override-file = "/secure/path/credentials.json"

Can also use environment variable:

export RATTLER_AUTH_FILE=/custom/path/credentials.json

change-ps1

change-ps1 · boolean · default: "true"

Whether to modify the shell prompt (PS1) when activating an environment.

change-ps1 = false  # Don't modify prompt

detached-environments

detached-environments · path

Directory to store environments outside workspace directories.

detached-environments = "/mnt/shared/pixi-envs"

Useful for:

• Shared environments across workspaces
• Network storage
• Faster rebuilds (keep environments between git clones)

Network Configuration

[mirrors]

mirrors · object

Configure channel mirrors for faster downloads or local caching.

[mirrors]
# Mirror conda-forge
"https://conda.anaconda.org/conda-forge" = [
  "https://prefix.dev/conda-forge",
  "https://mirror.example.com/conda-forge"
]

# Mirror multiple channels
"https://repo.anaconda.com/pkgs/main" = [
  "https://mirror1.example.com/main",
  "https://mirror2.example.com/main"
]

Pixi will try mirrors in order, falling back to the original if mirrors fail.

[proxy-config]

proxy-config · object

HTTP/HTTPS proxy configuration.

[proxy-config]
http = "http://proxy.example.com:8080"
https = "http://proxy.example.com:8080"
no-proxy = ["localhost", "127.0.0.1", ".example.com"]

Can also use environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.example.com

PyPI Configuration

[pypi-config]

pypi-config · object

PyPI index and package installation configuration.

[pypi-config]
index-url = "https://pypi.org/simple"
extra-index-urls = [
  "https://my-pypi.example.com/simple",
  "https://backup-pypi.example.com/simple"
]

# Index strategy
index-strategy = "first-index"  # or "unsafe-first-match", "unsafe-best-match"

# Binary/build control
no-binary = ["numpy", "scipy"]  # Don't use wheels
no-build = ["tensorflow"]  # Don't build from source
no-build-isolation = ["pyproject-toml"]  # No isolated build

# Prerelease handling
prerelease-mode = "disallow"  # or "allow", "if-necessary", "explicit"

index-url

Primary PyPI index:

[pypi-config]
index-url = "https://pypi.org/simple"

extra-index-urls

Additional PyPI indexes:

[pypi-config]
extra-index-urls = [
  "https://my-company.example.com/simple",
  "https://backup.example.com/simple"
]

index-strategy

How to search multiple indexes:

• first-index (default) - Only search first index that has the package
• unsafe-first-match - Use first match across all indexes
• unsafe-best-match - Use best version across all indexes

[pypi-config]
index-strategy = "first-index"

no-binary

Don’t use pre-built wheels:

[pypi-config]
no-binary = ["numpy", "scipy"]  # Build these from source

Or disable all binaries:

[pypi-config]
no-binary = true

no-build

Don’t build from source:

[pypi-config]
no-build = ["tensorflow"]  # Only use wheels

prerelease-mode

Handle pre-release versions:

• disallow (default) - Don’t use pre-releases
• allow - Allow pre-releases
• if-necessary - Use pre-releases if needed
• explicit - Only use explicitly requested pre-releases

[pypi-config]
prerelease-mode = "if-necessary"

Repodata Configuration

[repodata-config]

repodata-config · object

Control how channel repodata is fetched and cached.

[repodata-config]
disable-jlap = false  # Use JLAP compression
disable-bzip2 = false  # Use bzip2 compression
disable-zstd = false  # Use zstd compression

JLAP provides incremental updates to repodata, reducing bandwidth usage.

Complete Example

Here’s a complete configuration file with common settings:

# ~/.config/pixi/config.toml

# Default channels
default-channels = ["conda-forge", "bioconda"]

# TLS
tls-no-verify = false

# Authentication
authentication-override-file = "~/.pixi/credentials.json"

# Shell
change-ps1 = true

# Detached environments (optional)
# detached-environments = "~/.pixi/envs"

# Channel mirrors
[mirrors]
"https://conda.anaconda.org/conda-forge" = [
  "https://prefix.dev/conda-forge"
]

# Proxy (if needed)
# [proxy-config]
# http = "http://proxy.company.com:8080"
# https = "http://proxy.company.com:8080"
# no-proxy = ["localhost", "127.0.0.1", ".company.com"]

# PyPI configuration
[pypi-config]
index-url = "https://pypi.org/simple"
extra-index-urls = [
  "https://my-company.example.com/simple"
]
index-strategy = "first-index"
prerelease-mode = "if-necessary"

# Repodata
[repodata-config]
disable-jlap = false

Managing Configuration

View Configuration

# View all config
pixi config list

# View specific key
pixi config list default-channels

# View as JSON
pixi config list --json

Edit Configuration

# Edit global config
pixi config edit --global

# Edit local config
pixi config edit --local

# Use custom editor
pixi config edit --editor vim

Set Values

# Set a value
pixi config set default-channels '["conda-forge"]'

# Append to list
pixi config append default-channels bioconda

# Prepend to list
pixi config prepend default-channels my-channel

# Unset a value
pixi config unset tls-no-verify

Configuration Scopes

# Global (user-level)
pixi config set --global default-channels '["conda-forge"]'

# Local (workspace-level)
pixi config set --local default-channels '["conda-forge", "bioconda"]'

# System-wide
pixi config set --system default-channels '["internal-channel"]'

Use Cases

Corporate Environment

# Corporate proxy and mirrors
default-channels = ["internal-conda"]

[mirrors]
"https://conda.anaconda.org/conda-forge" = [
  "https://conda-mirror.company.com/conda-forge"
]

[proxy-config]
http = "http://proxy.company.com:8080"
https = "http://proxy.company.com:8080"
no-proxy = [".company.com", "localhost"]

[pypi-config]
index-url = "https://pypi.company.com/simple"

Development Machine

# Fast mirrors and local cache
default-channels = ["conda-forge"]
detached-environments = "/mnt/fast-ssd/pixi-envs"

[mirrors]
"https://conda.anaconda.org/conda-forge" = [
  "https://prefix.dev/conda-forge"
]

CI/CD Server

# Minimal, reproducible builds
default-channels = ["conda-forge"]
change-ps1 = false

[repodata-config]
disable-jlap = true  # More reliable in CI

Related

• pixi config - Manage configuration
• Environment Variables - Environment-based configuration
• CLI Options - Command-line configuration