Skip to main content
Pixi supports global configuration options that are not tied to a specific workspace. These settings are local to the machine and loaded from various configuration files.

​
Configuration Loading Order

Configuration files are loaded with the following priority (highest to lowest):
PriorityLocationDescription
7Command line arguments--tls-no-verify, --change-ps1=false, etc.
6your_project/.pixi/config.tomlProject-specific configuration
5$PIXI_HOME/config.tomlGlobal configuration in PIXI_HOME
4$HOME/.pixi/config.tomlGlobal configuration in user home
3$XDG_CONFIG_HOME/pixi/config.tomlXDG compliant user configuration
2$HOME/.config/pixi/config.tomlUser-specific configuration
1/etc/pixi/config.tomlSystem-wide configuration
Higher priority values override lower priority values. To find all locations where pixi looks for configuration files, run pixi info -vvv.

​
Core Configuration Options

​
default-channels

The default channels to use when running pixi init or pixi global install.
​
default-channels
array
default:"['conda-forge']"
Default channels for new projects
default-channels = ["conda-forge"]
The default-channels are only used when initializing a new workspace. Once initialized, the channels from the workspace manifest are used.

​
shell

Configure shell behavior when using pixi shell.
​
shell.change-ps1
boolean
default:"true"
When set to false, removes the (pixi) prefix from the shell prompt. Override with --change-ps1.
​
shell.force-activate
boolean
default:"false"
When set to true, re-activation always happens. Used with experimental use-environment-activation-cache.
​
shell.source-completion-scripts
boolean
default:"true"
When set to false, pixi will not source autocompletion scripts when entering the shell.
[shell]
change-ps1 = true
force-activate = false
source-completion-scripts = true

​
pinning-strategy

Strategy for pinning dependencies when running pixi add.
​
pinning-strategy
enum
default:"semver"
Available strategies:
  • no-pin: No pinning, resulting in *
  • semver: Pin to major for most versions, minor for v0 versions
  • exact-version: Pin to exact version ==1.2.3
  • major: Pin to major >=1.2.3, <2
  • minor: Pin to minor >=1.2.3, <1.3
  • latest-up: Pin to latest >=1.2.3
pinning-strategy = "semver"

​
detached-environments

Directory where pixi stores workspace environments (normally in .pixi/envs).
​
detached-environments
boolean | string
  • true: Store in cache directory
  • false: Store in .pixi/envs (default)
  • "/path/to/dir": Store in custom path
Using detached environments creates a disconnect between the workspace and its environments, requiring manual cleanup when deleting workspaces.
# Store in cache directory
detached-environments = true

# Or use custom path
detached-environments = "/opt/pixi/envs"
The resulting structure: 
/opt/pixi/envs
├── pixi-6837172896226367631
│   └── envs
└── PROJECT_NAME-HASH
    ├── envs
    └── solve-group-envs

​
concurrency

Configure concurrency limits for pixi operations.
​
concurrency.solves
integer
Maximum concurrent solves
​
concurrency.downloads
integer
default:"50"
Maximum concurrent downloads
[concurrency]
solves = 1
downloads = 12
Or via CLI: 
pixi config set concurrency.solves 1
pixi config set concurrency.downloads 12

​
proxy-config

Configure HTTP/HTTPS proxies for network operations.
​
proxy-config.https
string
HTTPS proxy URL (like https_proxy environment variable)
​
proxy-config.http
string
HTTP proxy URL (like http_proxy environment variable)
​
proxy-config.non-proxy-hosts
array
Domains that should bypass proxies
[proxy-config]
https = "https://proxy.company.com:8080"
http = "http://proxy.company.com:8080"
non-proxy-hosts = ["localhost", "internal.company.com"]
Environment variables like https_proxy have the highest priority and will override these settings.

​
tool-platform

Defines the platform used when installing build backends and tools.
​
tool-platform
string
Platform identifier (e.g., linux-64, osx-arm64)
tool-platform = "linux-64"
By default, pixi uses the current system platform. Override this for architectures with limited build backend support.

​
Experimental Features

​
use-environment-activation-cache

Cache environment activation to speed up pixi run and pixi shell. 
# Enable globally
pixi config set experimental.use-environment-activation-cache true --global

# Enable for workspace
pixi config set experimental.use-environment-activation-cache true --local
Cache structure in .pixi/activation-env-v0/: 
{
  "hash": "8d8344e0751d377a",
  "environment_variables": {
    "PATH": "/path/to/env/bin:...",
    "CONDA_PREFIX": "/path/to/env"
  }
}
Ignore cache with: 
pixi run --force-activate
pixi shell --force-activate
This is experimental because cache invalidation is complex. Use with caution in production environments.

​
Naming Convention

In pixi 0.20.1 and older, configuration options used snake_case. Since 0.20.2, kebab-case is used for consistency. Both formats are supported for backward compatibility.
Compatible options:
  • default_channels / default-channels
  • change_ps1 / change-ps1
  • tls_no_verify / tls-no-verify
  • authentication_override_file / authentication-override-file