Skip to content

Environment Variables

Configurable Environment Variables#

Pixi can also be configured via environment variables.

Name Description Default
PIXI_HOME Defines the directory where pixi puts its global data. HOME/.pixi
PIXI_CACHE_DIR Defines the directory where pixi puts its cache.
  • If PIXI_CACHE_DIR is not set, the RATTLER_CACHE_DIR environment variable is used.
  • If that is not set, XDG_CACHE_HOME/pixi is used when the directory exists.
  • If that is not set, the default cache directory of rattler::default_cache_dir is used.
PIXI_NO_CONFIG When set to a truthy value (e.g. 1), pixi skips loading system and user-level configuration files, both pixi's own (such as /etc/pixi/config.toml and ~/.pixi/config.toml) and the shared ones (such as /etc/rattler/config.toml). Project-local <project>/.pixi/config.toml is still loaded. Equivalent to passing --no-config. Useful in CI, scripts, and tests that need to be insulated from a developer's global settings. Not set.
PIXI_CONFIG_FILE Path to a configuration file to load instead of the system and user-level config files. Project-local <project>/.pixi/config.toml is still merged on top. Equivalent to passing --config-file <PATH>. Not set.
RATTLER_HOME Directory holding a shared config.toml that every rattler-based tool reads. It ranks above the other shared locations and below every pixi-specific one. Not set.
PIXI_OVERRIDE_PLATFORM Overrides the detected host platform used to select and install environments. Accepts any valid platform string (e.g. linux-aarch64, osx-arm64, win-64). Not set, pixi detects the current platform automatically.
PIXI_GIT_LFS Deprecated: set lfs = true on the git dependency in the manifest instead. When set to a truthy value (e.g. 1), pixi fetches Git LFS objects for git dependencies. Not set.
RATTLER_AUTH_FILE Overrides the default location of the credentials file. When set, this is the only source of authentication data used by pixi. See authentication docs for the file format.
  • If RATTLER_AUTH_FILE is not set, the system keyring is used.
  • If no keyring is available, file storage from ~/.rattler/credentials.json is used.
  • Additionally, .netrc file authentication is checked.
PIXI_NO_TELEMETRY If set to a non-empty value, disables the anonymous ping sent by the install scripts and by pixi self-update. See Telemetry. Not set (ping enabled).
DO_NOT_TRACK Same effect as PIXI_NO_TELEMETRY; honors the ecosystem-wide DO_NOT_TRACK convention. Not set (ping enabled).

Environment Variables Set By Pixi#

The following environment variables are set by Pixi, when using the pixi run, pixi shell, or pixi shell-hook command:

  • PIXI_WORKSPACE_ROOT: The root directory of the workspace. (Legacy alias: PIXI_PROJECT_ROOT.)
  • PIXI_WORKSPACE_NAME: The name of the workspace. (Legacy alias: PIXI_PROJECT_NAME.)
  • PIXI_WORKSPACE_MANIFEST: The path to the manifest file (pixi.toml). (Legacy alias: PIXI_PROJECT_MANIFEST.)
  • PIXI_WORKSPACE_VERSION: The version of the workspace. (Legacy alias: PIXI_PROJECT_VERSION.)
  • PIXI_PROMPT: The prompt to use in the shell, also used by pixi shell itself.
  • PIXI_ENVIRONMENT_NAME: The name of the environment, defaults to default.
  • PIXI_ENVIRONMENT_PLATFORMS: Comma separated list of platforms supported by the project.
  • CONDA_PREFIX: The path to the environment. (Used by multiple tools that already understand conda environments)
  • CONDA_DEFAULT_ENV: The name of the environment. (Used by multiple tools that already understand conda environments)
  • PATH: We prepend the bin directory of the environment to the PATH variable, so you can use the tools installed in the environment directly.
  • INIT_CWD: ONLY IN pixi run: The directory where the command was run from.

Note

Even though the variables are environment variables these cannot be overridden. E.g. you can not change the root of the workspace by setting PIXI_WORKSPACE_ROOT in the environment.

Note

The PIXI_PROJECT_* variables are kept as legacy aliases of their PIXI_WORKSPACE_* counterparts and are set to the same values. Prefer the PIXI_WORKSPACE_* names. Where pixi reads these variables as input (PIXI_WORKSPACE_MANIFEST/PIXI_PROJECT_MANIFEST and PIXI_WORKSPACE_ROOT/PIXI_PROJECT_ROOT), the PIXI_WORKSPACE_* variant takes precedence if both are set to different values.

Environment Variable Priority#

The following priority rule applies for environment variables: task.env > activation.env > activation.scripts > activation scripts of dependencies > outside environment variables. Variables defined at a higher priority will override those defined at a lower priority.

Warning

In older versions of Pixi, this priority was not well-defined, and there are a number of known deviations from the current priority which exist in some older versions. Please see the warning in the advanced tasks documentation for further details and migration guidance.

Example 1: task.env > activation.env#

In pixi.toml, we defined an environment variable HELLO_WORLD in both tasks.hello and activation.env.

When we run echo $HELLO_WORLD, it will output: 

Hello world!

pixi.toml
[tasks.hello]
cmd = "echo $HELLO_WORLD"
env = { HELLO_WORLD = "Hello world!" }
[activation.env]
HELLO_WORLD = "Activate!"
Example 2: activation.env > activation.scripts#

In pixi.toml, we defined the same environment variable DEBUG_MODE in both activation.env and in the activation script file setup.sh. When we run echo Debug mode: $DEBUG_MODE, it will output: 

Debug mode: enabled

pixi.toml
[activation.env]
DEBUG_MODE = "enabled"

[activation]
scripts = ["setup.sh"]
setup.sh
export DEBUG_MODE="disabled"
Example 3: activation.scripts > activation scripts of dependencies#

In pixi.toml, we have our local activation script and a dependency my-package that also sets environment variables through its activation scripts. When we run echo Library path: $LIB_PATH, it will output: 

Library path: /my/lib

pixi.toml
[activation]
scripts = ["local_setup.sh"]

[dependencies]
my-package = "*"  # This package has its own activation scripts that set LIB_PATH="/dep/lib"
local_setup.sh
export LIB_PATH="/my/lib"

Example 4: activation scripts of dependencies > outside environment variable#

If we have a dependency that sets PYTHON_PATH and the same variable is already set in the outside environment. When we run echo Python path: $PYTHON_PATH, it will output: 

Python path: /pixi/python

# Outside environment
export PYTHON_PATH="/system/python"
pixi.toml
[dependencies]
python-utils = "*"  # This package sets PYTHON_PATH="/pixi/python" in its activation scripts

Example 5: Complex Example - All priorities combined#

In pixi.toml, we define the same variable APP_CONFIG across multiple levels:

pixi.toml
[tasks.start]
cmd = "echo Config: $APP_CONFIG"
env = { APP_CONFIG = "task-specific" }

[activation.env]
APP_CONFIG = "activation-env"

[activation]
scripts = ["app_setup.sh"]

[dependencies]
config-loader = "*"  # Sets APP_CONFIG="dependency-config"
app_setup.sh
export APP_CONFIG="activation-script"

# Outside environment
export APP_CONFIG="system-config"

Since task.env has the highest priority, when we run pixi run start it will output:

Config: task-specific