Environment Activation

How pixi activates environments and sets environment variables

Pixi activates environments differently than conda, providing a more streamlined experience that doesn’t require modifying shell configuration files.

How Pixi Shell Works

The pixi shell command launches a fresh shell with the environment activated, instead of modifying your current shell like conda activate.

pixi shell

To exit, simply close the shell:

exit  # or press Ctrl+D

Activation Mechanism (Unix)

On Unix systems, pixi creates a “fake” PTY session:

1. Launches a new shell process
2. Sends an activation command to stdin: source /tmp/activation-env-12345.sh
3. Waits for PIXI_ENV_ACTIVATED echo to confirm success
4. If no confirmation after 3 seconds, issues a warning

# What pixi does internally
source /tmp/activation-env-12345.sh
echo "PIXI_ENV_ACTIVATED"

Automatic Shell Completions

Shell completions for tools in your environment are loaded automatically:

pixi shell
# Completions for git, cargo, npm, etc. are now available

To disable:

[shell]
source-completion-scripts = false

Environment Variables Set by Pixi

Pixi sets these variables when running pixi run, pixi shell, or pixi shell-hook:

PIXI_PROJECT_ROOT · string

The root directory of the project

PIXI_PROJECT_NAME · string

The name of the project from the manifest

PIXI_PROJECT_MANIFEST · string

Path to the manifest file (pixi.toml or pyproject.toml)

PIXI_PROJECT_VERSION · string

The version of the project

PIXI_PROMPT · string

The prompt to use in the shell

PIXI_ENVIRONMENT_NAME · string · default: "default"

Name of the active environment

PIXI_ENVIRONMENT_PLATFORMS · string

Comma-separated list of platforms supported by the project

CONDA_PREFIX · string

Path to the environment (conda compatibility)

CONDA_DEFAULT_ENV · string

Name of the environment (conda compatibility)

PATH · string

Prepended with environment’s bin directory

INIT_CWD · string

ONLY in pixi run: Directory where command was run from

These variables cannot be overridden by users. For example, setting PIXI_PROJECT_ROOT in your environment won’t change where pixi looks for the project.

Environment Variable Priority

Variables are set with the following priority (highest to lowest):

task.env > activation.env > activation.scripts > dependency scripts > outside variables

Example 1: task.env > activation.env

[tasks.hello]
cmd = "echo $HELLO_WORLD"
env = { HELLO_WORLD = "Hello world!" }

[activation.env]
HELLO_WORLD = "Activate!"

pixi run hello
# Output: Hello world!

The task environment variable wins.

Example 2: activation.env > activation.scripts

[activation.env]
DEBUG_MODE = "enabled"

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

setup.sh

export DEBUG_MODE="disabled"

pixi run echo $DEBUG_MODE
# Output: enabled

The manifest activation.env wins over activation scripts.

Example 3: activation.scripts > dependency scripts

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

[dependencies]
my-package = "*"  # Has activation scripts setting LIB_PATH="/dep/lib"

local_setup.sh

export LIB_PATH="/my/lib"

pixi run echo $LIB_PATH
# Output: /my/lib

Local activation scripts override dependency scripts.

Example 4: dependency scripts > outside variables

# Outside environment
export PYTHON_PATH="/system/python"

[dependencies]
python-utils = "*"  # Sets PYTHON_PATH="/pixi/python"

pixi run echo $PYTHON_PATH
# Output: /pixi/python

Dependency activation scripts override outside environment.

Example 5: Complete Priority Chain

[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"

pixi run start
# Output: Config: task-specific

The task environment variable has the highest priority.

In older versions of pixi, this priority was not well-defined. If you’re upgrading from an old version, review your environment variable usage.

Activation Cache (Experimental)

Cache environment activation to speed up repeated pixi run and pixi shell invocations.

Enable Activation Cache

# 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

Cache files are stored in .pixi/activation-env-v0/:

tree .pixi/activation-env-v0/

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

Cache Contents

{
  "hash": "8d8344e0751d377a",
  "environment_variables": {
    "PATH": "/path/to/env/bin:/usr/bin",
    "CONDA_PREFIX": "/path/to/env",
    "PIXI_PROJECT_ROOT": "/path/to/project"
  }
}

The hash includes:

• Lock file data for the environment
• activation.scripts from manifest
• activation.env from manifest

Force Reactivation

Ignore the cache and force full activation:

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

Or configure globally:

[shell]
force-activate = true

This is experimental because cache invalidation is complex. Use with caution in production environments.

Common Issues with Pixi Shell

Some shell configurations can interfere with pixi’s activation mechanism.

WSL Issue

~/.bashrc

# This can prevent pixi shell from working
wsl.exe -d wsl-vpnkit --cd /app service wsl-vpnkit start

The wsl.exe command takes over stdin and prevents activation.

Alternative Shell in bashrc

~/.bashrc

# This breaks pixi shell
if [[ $- = *i* ]]; then
  exec ~/.pixi/bin/fish
fi

If you want to start an alternative shell, do so from ~/.bash_profile or ~/.profile instead of ~/.bashrc.

Alternative: Shell Hook

If pixi shell doesn’t work due to the issues above, use pixi shell-hook:

Bash/Zsh

~/.bashrc or ~/.zshrc

eval "$(pixi shell-hook)"

Fish

~/.config/fish/config.fish

pixi shell-hook | source

PowerShell

$PROFILE

Invoke-Expression (&pixi shell-hook)

This provides conda-style activation without the PTY mechanism.

Customizing the Prompt

By default, pixi adds (pixi) to your shell prompt.

Disable Prompt Modification

[shell]
change-ps1 = false

Or via CLI:

pixi shell --change-ps1=false

Custom Prompt

The PIXI_PROMPT variable contains the prompt prefix:

echo $PIXI_PROMPT
# Output: (pixi:default)

Use in your custom prompt:

~/.bashrc

if [ -n "$PIXI_PROMPT" ]; then
  PS1="${PIXI_PROMPT} ${PS1}"
fi

Best Practices

1. Use pixi run for tasks instead of manually activating environments
2. Use pixi shell for interactive work when you need environment access
3. Avoid modifying PIXI_ variables* as they’re managed by pixi
4. Document activation scripts to help team members understand environment setup
5. Test activation after adding new activation scripts
6. Use shell-hook if pixi shell doesn’t work with your shell configuration
7. Enable activation cache for large projects to improve performance

Don’t mix conda activate and pixi shell in the same shell session. They use different activation mechanisms and can conflict.