Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/prefix-dev/pixi/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

%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

Build docs developers (and LLMs) love

Get started for freeTalk to us