Global Configuration

Configure pixi globally with config.toml

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

Linux

Priority	Location	Description
7	Command line arguments	--tls-no-verify, --change-ps1=false, etc.
6	your_project/.pixi/config.toml	Project-specific configuration
5	$PIXI_HOME/config.toml	Global configuration in PIXI_HOME
4	$HOME/.pixi/config.toml	Global configuration in user home
3	$XDG_CONFIG_HOME/pixi/config.toml	XDG compliant user configuration
2	$HOME/.config/pixi/config.toml	User-specific configuration
1	/etc/pixi/config.toml	System-wide configuration

macOS

Priority	Location	Description
7	Command line arguments	--tls-no-verify, --change-ps1=false, etc.
6	your_project/.pixi/config.toml	Project-specific configuration
5	$PIXI_HOME/config.toml	Global configuration in PIXI_HOME
4	$HOME/.pixi/config.toml	Global configuration in user home
3	$HOME/Library/Application Support/pixi/config.toml	User-specific configuration
2	$XDG_CONFIG_HOME/pixi/config.toml	XDG compliant user configuration
1	/etc/pixi/config.toml	System-wide configuration

Windows

Priority	Location	Description
6	Command line arguments	--tls-no-verify, --change-ps1=false, etc.
5	your_project\.pixi\config.toml	Project-specific configuration
4	%PIXI_HOME%\config.toml	Global configuration in PIXI_HOME
3	%USERPROFILE%\.pixi\config.toml	Global configuration in user home
2	%APPDATA%\pixi\config.toml	User-specific configuration
1	C:\ProgramData\pixi\config.toml	System-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