Global Configuration

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

System configuration (platform-dependent)
Global configuration (user-level)
Local configuration (workspace-level)
Environment variables
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

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

Manifest Files

Configuration

​Configuration Locations

​Global Configuration Paths

​Local Configuration

​Configuration Format

​Configuration Options

​default-channels

​tls-no-verify

​authentication-override-file

​change-ps1

​detached-environments

​Network Configuration

​[mirrors]

​[proxy-config]

​PyPI Configuration

​[pypi-config]

​index-url

​extra-index-urls

​index-strategy

​no-binary

​no-build

​prerelease-mode

​Repodata Configuration

​[repodata-config]

​Complete Example

​Managing Configuration

​View Configuration

​Edit Configuration

​Set Values

​Configuration Scopes

​Use Cases

​Corporate Environment

​Development Machine

​CI/CD Server

​Related

Configuration Locations

Global Configuration Paths

Local Configuration

Configuration Format

Configuration Options

`default-channels`

`tls-no-verify`

`authentication-override-file`

`change-ps1`

`detached-environments`

Network Configuration

`[mirrors]`

`[proxy-config]`

PyPI Configuration

`[pypi-config]`

`index-url`

`extra-index-urls`

`index-strategy`

`no-binary`

`no-build`

`prerelease-mode`

Repodata Configuration

`[repodata-config]`

Complete Example

Managing Configuration

View Configuration

Edit Configuration

Set Values

Configuration Scopes

Use Cases

Corporate Environment

Development Machine

CI/CD Server

Related