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.

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_PROJECT_ROOT: The root directory of the project.
PIXI_PROJECT_NAME: The name of the project.
PIXI_PROJECT_MANIFEST: The path to the manifest file (pixi.toml).
PIXI_PROJECT_VERSION: The version of the project.
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 project by setting PIXI_PROJECT_ROOT in the environment.

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

Environment Variables

Configurable Environment Variables#