The Configuration of Pixi Itself#

Apart from the workspace specific configuration Pixi supports configuration options which are not required for the workspace to work but are local to the machine. The configuration is loaded in the following order:

LinuxmacOSWindows

Priority	Location	Comments
7	Command line arguments (`--tls-no-verify`, `--change-ps1=false`, etc.)	Configuration via command line arguments
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 the user home directory.
3	`$XDG_CONFIG_HOME/pixi/config.toml`	XDG compliant user-specific configuration
2	`$HOME/.config/pixi/config.toml`	User-specific configuration
1	`/etc/pixi/config.toml`	System-wide configuration

Priority	Location	Comments
7	Command line arguments (`--tls-no-verify`, `--change-ps1=false`, etc.)	Configuration via command line arguments
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 the user home directory.
3	`$HOME/Library/Application Support/pixi/config.toml`	User-specific configuration
2	`$XDG_CONFIG_HOME/pixi/config.toml`	XDG compliant user-specific configuration
1	`/etc/pixi/config.toml`	System-wide configuration

Priority	Location	Comments
6	Command line arguments (`--tls-no-verify`, `--change-ps1=false`, etc.)	Configuration via command line arguments
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 the user home directory.
2	`%APPDATA%\pixi\config.toml`	User-specific configuration
1	`C:\ProgramData\pixi\config.toml`	System-wide configuration

Note

The highest priority wins. If a configuration file is found in a higher priority location, the values from the configuration read from lower priority locations are overwritten.

Note

To find the locations where pixi looks for configuration files, run pixi info -vvv.

Configuration options#

Naming convention in configuration

In Pixi 0.20.1 and older the global configuration options used snake_case which we've changed to kebab-case for consistency with the rest of the configuration. For backwards compatibility, the following configuration options can still be written in snake_case:

- `default_channels`
- `change_ps1`
- `tls_no_verify`
- `authentication_override_file`
- `mirrors` and its sub-options
- `repodata_config` and its sub-options

The following reference describes all available configuration options.

`default-channels`#

The default channels to select when running pixi init or pixi global install. This defaults to only conda-forge.

config.toml

default-channels = ["conda-forge"]

Note

The default-channels are only used when initializing a new workspace. Once initialized the channels are used from the workspace manifest.

`shell`#

change-ps1: When set to false, the (pixi) prefix in the shell prompt is removed. This applies to the pixi shell subcommand. You can override this from the CLI with --change-ps1.
force-activate: When set to true the re-activation of the environment will always happen. This is used in combination with the experimental feature use-environment-activation-cache.
source-completion-scripts: When set to false, Pixi will not source the autocompletion scripts of the environment when going into the shell.

config.toml

[shell]
change-ps1 = false
force-activate = true
source-completion-scripts = false

`tls-no-verify`#

When set to true, TLS certificate verification is disabled for all network connections, including both conda channels and PyPI registries. You can override this from the CLI with --tls-no-verify.

Warning

This is a security risk and should only be used for testing purposes or internal networks.

This is a global setting that affects all connections. If you only need to bypass TLS verification for specific PyPI hosts, consider using pypi-config.allow-insecure-host instead for more granular control.

Implementation detail and limitations

For PyPI operations, since uv does not support a global TLS verification disable flag, pixi automatically adds all configured PyPI index hosts to the trusted hosts list when tls-no-verify is enabled. For the main PyPI index, files.pythonhosted.org (the download host) is also automatically added. Important limitation: If your custom PyPI index redirects package downloads to a different host (e.g., a separate CDN or artifact server), that download host will not be automatically trusted, even with tls-no-verify set. In these cases, you must manually add the download host to pypi-config.allow-insecure-host.

config.toml

tls-no-verify = false

`tls-root-certs`#

Controls which TLS root certificates are used for HTTPS connections. This affects both conda channels and PyPI registries.

Available options:

webpki (default): Uses bundled Mozilla root certificates. This is the most portable option.
native: Uses the system certificate store. Required for corporate environments with custom CA certificates.
all: Uses both bundled Mozilla certificates and the system certificate store.

You can override this from the CLI with --tls-root-certs.

Build-dependent behavior

This setting only has an effect with rustls-tls builds (standalone pixi binaries from GitHub releases). For native-tls builds (conda-forge packages), the system's TLS library is used, which always uses system certificates. In this case, the setting is accepted but has no effect.

config.toml

# Which TLS root certificates to use for HTTPS connections.
# Options: "webpki" (bundled Mozilla roots), "native" (system store), "all" (both)
# Default is "webpki" for portability. Use "native" or "all" for corporate environments
# with custom CA certificates.
# Note: This setting only has an effect with rustls-tls builds (standalone pixi).
# For native-tls builds (conda-forge), system certificates are always used.
tls-root-certs = "native"

`authentication-override-file`#

Override from where the authentication information is loaded. Usually, we try to use the keyring to load authentication data from, and only use a JSON file as a fallback. This option allows you to force the use of a JSON file. Read more in the authentication section.

config.toml

authentication-override-file = "/path/to/your/override.json"

`detached-environments`#

The directory where Pixi stores the workspace environments, what would normally be placed in the .pixi/envs folder in a workspace's root. It doesn't affect the environments built for pixi global. The location of environments created for a pixi global installation can be controlled using the PIXI_HOME environment variable.

Warning

We recommend against using this because any environment created for a workspace is no longer placed in the same folder as the workspace. This creates a disconnect between the workspace and its environments and manual cleanup of the environments is required when deleting the workspace.

However, in some cases, this option can still be very useful, for instance to:

force the installation on a specific filesystem/drive.
install environments locally but keep the workspace on a network drive.
let a system-administrator have more control over all environments on a system.

This field can consist of two types of input.

A boolean value, true or false, which will enable or disable the feature respectively. (not "true" or "false", this is read as false)
A string value, which will be the absolute path to the directory where the environments will be stored.

config.toml

detached-environments = true

or:

config.toml

detached-environments = "/opt/pixi/envs"

The environments will be stored in the cache directory when this option is true. When you specify a custom path the environments will be stored in that directory.

Per-kind path override

You can also pin just the detached-environments path via the [cache] table (cache.detached-environments), which is convenient on HPC where this cache typically belongs on node-local scratch even when the rest of the pixi cache lives on a shared network filesystem.

The resulting directory structure will look like this:

/opt/pixi/envs
├── pixi-6837172896226367631
│   └── envs
└── NAME_OF_PROJECT-HASH_OF_ORIGINAL_PATH
    ├── envs # the runnable environments
    └── solve-group-envs # If there are solve groups

`pinning-strategy`#

The strategy to use for pinning dependencies when running pixi add. The default is semver but you can set the following:

no-pin: No pinning, resulting in an unconstraint dependency. *
semver: Pinning to the latest version that satisfies the semver constraint. Resulting in a pin to major for most versions and to minor for v0 versions.
exact-version: Pinning to the exact version, 1.2.3 -> ==1.2.3.
major: Pinning to the major version, 1.2.3 -> >=1.2.3, <2.
minor: Pinning to the minor version, 1.2.3 -> >=1.2.3, <1.3.
latest-up: Pinning to the latest version, 1.2.3 -> >=1.2.3.

config.toml

pinning-strategy = "no-pin"

`mirrors`#

Configuration for conda channel-mirrors, more info below.

config.toml

[mirrors]
# redirect all requests for conda-forge to the prefix.dev mirror
"https://conda.anaconda.org/conda-forge" = ["https://prefix.dev/conda-forge"]

# redirect all requests for bioconda to one of the three listed mirrors
# Note: for repodata we try the first mirror first.
"https://conda.anaconda.org/bioconda" = [
  "https://conda.anaconda.org/bioconda",
  # OCI registries are also supported
  "oci://ghcr.io/channel-mirrors/bioconda",
  # S3-compatible storage is also supported
  "s3://my-s3-bucket/bioconda",
  "https://prefix.dev/bioconda",
]

`proxy-config`#

pixi respects the proxy environments such as https_proxy with the highest priority. Also we can set the proxies in proxy-config table of the pixi config, which affect all the pixi network actions, such as resolve, self-update, download, etc. Now proxy-config table supports the following options:

https and http: The proxy url for https:// or http:// url, works like https_proxy and http_proxy environments.
non-proxy-hosts: A list of domains which should bypass proxies.

config.toml

[proxy-config]
http = "http://proxy.example.com:8080/"
https = "http://proxy.example.com:8080/"
non-proxy-hosts = [".cn", "localhost", "[::1]"]

`repodata-config`#

Configuration for repodata fetching.

config.toml

[repodata-config]
# disable fetching of bz2 or zstd repodata files.
# This should only be used for specific old versions of artifactory and other non-compliant
# servers.
disable-bzip2 = true   # don't try to download repodata.json.bz2
disable-sharded = true # don't try to download sharded repodata
disable-zstd = true    # don't try to download repodata.json.zst

The above settings can be overridden on a per-channel basis by specifying a channel prefix in the configuration.

config.toml

[repodata-config."https://prefix.dev"]
disable-sharded = false

`pypi-config`#

To setup a certain number of defaults for the usage of PyPI registries. You can use the following configuration options:

index-url: The default index URL to use for PyPI packages. This will be added to a manifest file on a pixi init.
extra-index-urls: A list of additional URLs to use for PyPI packages. This will be added to a manifest file on a pixi init.
keyring-provider: Allows the use of the keyring python package to store and retrieve credentials.
allow-insecure-host: A list of host names (without protocol or port) for which TLS certificate verification should be disabled when accessing PyPI registries. This is useful when working with internal PyPI mirrors that use self-signed certificates. For disabling TLS verification globally for all connections, use tls-no-verify instead.

config.toml

[pypi-config]
# Main index url
index-url = "https://pypi.org/simple"
# list of additional urls
extra-index-urls = ["https://pypi.org/simple2"]
# can be "subprocess" or "disabled"
keyring-provider = "subprocess"
# allow insecure connections to host
allow-insecure-host = ["localhost:8080"]

index-url and extra-index-urls are not globals

Unlike pip, these settings, with the exception of keyring-provider will only modify the pixi.toml/pyproject.toml file and are not globally interpreted when not present in the manifest. This is because we want to keep the manifest file as complete and reproducible as possible.

`s3-options`#

Configuration for S3 authentication. This will lead to Pixi not using AWS's default credentials but instead use the credentials from the Pixi authentication storage, see the S3 section for more information.

config.toml

[s3-options.my-bucket]
endpoint-url = "https://my-s3-compatible-host.com"
force-path-style = true
region = "us-east-1"

`concurrency`#

Configure multiple settings to limit or extend the concurrency of pixi.

config.toml

[concurrency]
# The maximum number of concurrent downloads
# Defaults to 50 as that was found to be a good balance between speed and stability
downloads = 5

# The maximum number of concurrent dependency resolves
# Defaults to a heuristic based on the number of cores on the system
solves = 2

Set them through the CLI with:

pixi config set concurrency.solves 1
pixi config set concurrency.downloads 12

`run-post-link-scripts`#

Configure whether pixi should execute post-link and pre-unlink scripts or not.

Some packages contain post-link scripts (bat or sh files) that are executed after a package is installed. We deem these scripts as insecure because they can contain arbitrary code that is executed on the user's machine without the user's consent. By default, the value of run-post-link-scripts is set to false which prevents the execution of these scripts.

However, you can opt-in on a global (or workspace) basis by setting the value to insecure (e.g. by running pixi config set --local run-post-link-scripts insecure).

In the future we are planning to add a sandbox mode to execute these scripts in a controlled environment.

config.toml

run-post-link-scripts = "false" # set to "insecure" to allow running post-link scripts

`tool-platform`#

Defines the platform used when installing "tools" like build backends. By default pixi uses the platform of the current system, but you can override it to use a different platform. This can be useful if you are running pixi on an architecture for which there is fewer support for certain build backends.

config.toml

tool-platform = "win-64" # force tools like build backends to be installed for a specific platform

Virtual packages

The virtual packages for the tool platform are detected from the current system. If the tool platform is for a different operating system than the current system, no virtual packages will be used.

`cache`#

The [cache] table lets you redirect specific pixi caches independently.

config.toml

[cache]
# Override for the cache root. Equivalent to setting PIXI_CACHE_DIR.
# Per-kind fields below override this on a cache-by-cache basis.
root = "/shared/hpc/pixi-cache"

# Per-cache absolute path overrides.
build-tool-environments = "/local/scratch/cached-build-tool-envs"
conda-packages = "/shared/hpc/pkgs"                               # conda package cache
detached-environments = "/local/scratch/envs"
exec-environments = "/local/scratch/cached-envs"
pypi-mapping = "/local/scratch/conda-pypi-mapping"                # conda<->pypi name mapping
pypi-wheels = "/shared/hpc/uv-cache"                              # uv wheel cache
repodata = "/shared/hpc/repodata"                                 # repodata cache

# How to handle a cache that lives on a network filesystem.
# - "auto" (default): redirect kinds that prefer local storage to node-local
#   scratch (chosen from $SLURM_TMPDIR / $PBS_JOBFS / $SCRATCH / $TMPDIR);
#   leave shared-friendly kinds (conda-packages, repodata, pypi-wheels) put.
# - "always": redirect every kind when the root looks like netfs.
# - "never": never redirect.
netfs-redirect = "auto"

Resolution order#

For each cache kind, pixi resolves the directory in this order (highest priority first):

The matching PIXI_CACHE_<KIND>_DIR environment variable, if set (see Environment-variable escape hatches).
The matching [cache.<kind>] path from this config, if set.
The cache root, joined with the kind's subdirectory: 1. PIXI_CACHE_DIR environment variable 2. RATTLER_CACHE_DIR environment variable 3. [cache.root] from this config 4. $XDG_CACHE_HOME/pixi (when it exists) 5. The platform default (e.g. ~/Library/Caches/rattler/cache on macOS)
If the resolved path is on a network filesystem and the kind is not "shared-friendly", auto-redirect to node-local scratch (see netfs-redirect below).

Cache kinds#

The fields under [cache] map one-to-one to the caches pixi maintains:

Field	Cache contents	Default behavior on netfs
`conda-packages`	Extracted conda packages (`pkgs`)	Stay shared
`repodata`	`repodata.json` cache	Stay shared
`pypi-wheels`	uv wheel cache (`uv-cache`)	Stay shared
`pypi-mapping`	conda↔PyPI name mapping	Redirect to node-local
`exec-environments`	Cached `pixi exec` envs	Redirect to node-local
`build-tool-environments`	Cached build-tool envs	Redirect to node-local
`detached-environments`	Workspace envs when `detached-environments` is `true`	Redirect to node-local

`netfs-redirect`#

Controls the auto-redirect behavior when the resolved cache root lives on a network filesystem (NFS, SMB/CIFS, FUSE, autofs):

"auto" (default): redirect only the kinds that prefer node-local storage (those marked "Redirect to node-local" above).
"always": redirect every kind to node-local scratch when the root is on netfs.
"never": do not redirect anything, even when on netfs.

A per-kind path override ([cache.<kind>] = "...") always wins over the auto-redirect logic.

The redirect target is chosen from the first non-netfs candidate among $SLURM_TMPDIR, $PBS_JOBFS, $SCRATCH, and $TMPDIR, falling back to the system temp directory.

Path syntax#

All path fields under [cache] (including root and every per-kind override) follow the same rules:

Absolute paths are required. Relative paths are rejected at config-load time with an error naming the offending field. This is enforced because config.toml is loaded from many layered locations (system, XDG, workspace) and "relative to which one?" is ambiguous.
~ is expanded to the user's home directory. For example, pypi-mapping = "~/scratch/mapping" resolves to <home>/scratch/mapping. Expansion happens once, at config-load time.
No environment-variable substitution. Strings like $HOME or ${SCRATCH} are treated as literal directory names. If you need an environment-variable-driven cache root, use the PIXI_CACHE_DIR environment variable instead — it is consulted before [cache.root].

Environment-variable escape hatches#

Every [cache] field can be overridden by an environment variable. Env vars take precedence over config.toml, so they're useful on shared CI/HPC nodes where editing the config file is awkward.

Per-kind path overrides. Each one is equivalent to the matching [cache.<kind>] field. Setting one bypasses the auto-redirect logic for that kind and uses the path verbatim.

Environment variable	Equivalent TOML field
`PIXI_CACHE_CONDA_PACKAGES_DIR`	`cache.conda-packages`
`PIXI_CACHE_REPODATA_DIR`	`cache.repodata`
`PIXI_CACHE_PYPI_WHEELS_DIR`	`cache.pypi-wheels`
`PIXI_CACHE_PYPI_MAPPING_DIR`	`cache.pypi-mapping`
`PIXI_CACHE_EXEC_ENVIRONMENTS_DIR`	`cache.exec-environments`
`PIXI_CACHE_BUILD_TOOL_ENVIRONMENTS_DIR`	`cache.build-tool-environments`
`PIXI_CACHE_DETACHED_ENVIRONMENTS_DIR`	`cache.detached-environments`

Redirect policy override.

PIXI_CACHE_NETFS_REDIRECT = auto | always | never — overrides [cache.netfs-redirect]. An unrecognized value is logged and ignored (config falls through).

Detection escape hatches. These force the network-filesystem detection itself rather than the policy. They're intended for tests, CI, and one-off debugging:

PIXI_DISABLE_NETFS_REDIRECT=1 — treat all paths as local; never redirect.
PIXI_FORCE_NETFS_REDIRECT=1 — treat all paths as netfs; redirect kinds that prefer local storage.

For persistent behavior, prefer [cache.netfs-redirect] or PIXI_CACHE_NETFS_REDIRECT.

Experimental#

This allows the user to set specific experimental features that are not yet stable.

Please write a GitHub issue and add the flag experimental to the issue if you find issues with the feature you activated.

Caching environment activations#

Turn this feature on from configuration with the following command:

# For all of your workspaces
pixi config set experimental.use-environment-activation-cache true --global

# For a specific workspace
pixi config set experimental.use-environment-activation-cache true --local

This will cache the environment activation in the .pixi/activation-env-v0 folder in the workspace root. It will create a json file for each environment that is activated, and it will be used to activate the environment in the future.

> tree .pixi/activation-env-v0/
.pixi/activation-env-v0/
├── activation_default.json
└── activation_lint.json

> cat  .pixi/activation-env-v0/activation_lint.json
{"hash":"8d8344e0751d377a","environment_variables":{<ENVIRONMENT_VARIABLES_USED_IN_ACTIVATION>}}

The hash is a hash of the data on that environment in the pixi.lock, plus some important information on the environment activation. Like [activation.scripts] and [activation.env] from the manifest file.
The environment_variables are the environment variables that are set when activating the environment.

You can ignore the cache by running:

pixi run/shell/shell-hook --force-activate

Set the configuration with:

config.toml

[experimental]
# Enable the use of the environment activation cache
use-environment-activation-cache = true

Why is this experimental?

This feature is experimental because the cache invalidation is very tricky, and we don't want to disturb users that are not affected by activation times.

Mirror configuration#

You can configure mirrors for conda channels. We expect that mirrors are exact copies of the original channel. The implementation will look for the mirror key (a URL) in the mirrors section of the configuration file and replace the original URL with the mirror URL.

To also include the original URL, you have to repeat it in the list of mirrors.

The mirrors are prioritized based on the order of the list. We attempt to fetch the repodata (the most important file) from the first mirror in the list. The repodata contains all the SHA256 hashes of the individual packages, so it is important to get this file from a trusted source.

You can also specify mirrors for an entire "host", e.g.

config.toml

[mirrors]
"https://conda.anaconda.org" = ["https://prefix.dev/"]
# prefix.dev doesn't mirror conda-forge's label channels
# pixi uses the longest matching prefix for the mirror
"https://conda.anaconda.org/conda-forge/label" = [
  "https://conda.anaconda.org/conda-forge/label",
]

This will forward all request to channels on anaconda.org to prefix.dev. Channels that are not currently mirrored on prefix.dev will fail in the above example. You can override the behavior for specific channels (like conda-forge's label channels) by providing a longer prefix that points to itself.

OCI Mirrors#

You can also specify mirrors on the OCI registry. There is a public mirror on the Github container registry (ghcr.io) that is maintained by the conda-forge team. You can use it like this:

config.toml

[mirrors]
"https://conda.anaconda.org/conda-forge" = [
  "oci://ghcr.io/channel-mirrors/conda-forge",
]

The GHCR mirror also contains bioconda packages. You can search the available packages on Github.

Mirrors for PyPi resolving and PyPi package downloading#

The mirrors also affect the PyPi resolving and downloading steps of uv. You can set mirrors for the main pypi index and extra indices. But the base part of downloading urls may vary from their index urls. For example, the default pypi index is https://pypi.org/simple, and the package downloading urls are in the form of https://files.pythonhosted.org/packages/<h1>/<h2>/<hash>/<package>.whl. You need two mirror config entries for https://pypi.org/simple and https://files.pythonhosted.org/packages.

The Configuration of Pixi Itself#

Configuration options#

default-channels#

shell#

tls-no-verify#

tls-root-certs#

authentication-override-file#

detached-environments#

pinning-strategy#

mirrors#

proxy-config#

repodata-config#

pypi-config#

s3-options#

concurrency#

run-post-link-scripts#

tool-platform#

cache#

Resolution order#

Cache kinds#

netfs-redirect#

Path syntax#

Environment-variable escape hatches#

Experimental#

Caching environment activations#

Mirror configuration#

OCI Mirrors#

Mirrors for PyPi resolving and PyPi package downloading#

`default-channels`#

`shell`#

`tls-no-verify`#

`tls-root-certs`#

`authentication-override-file`#

`detached-environments`#

`pinning-strategy`#

`mirrors`#

`proxy-config`#

`repodata-config`#

`pypi-config`#

`s3-options`#

`concurrency`#

`run-post-link-scripts`#

`tool-platform`#

`cache`#

`netfs-redirect`#