> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/prefix-dev/pixi/llms.txt
> Use this file to discover all available pages before exploring further.
# 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`.
```bash theme={null}
pixi shell
```
To exit, simply close the shell:
```bash theme={null}
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
```bash theme={null}
# 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:
```bash theme={null}
pixi shell
# Completions for git, cargo, npm, etc. are now available
```
To disable:
```toml theme={null}
[shell]
source-completion-scripts = false
```
## Environment Variables Set by Pixi
Pixi sets these variables when running `pixi run`, `pixi shell`, or `pixi shell-hook`:
The root directory of the project
The name of the project from the manifest
Path to the manifest file (`pixi.toml` or `pyproject.toml`)
The version of the project
The prompt to use in the shell
Name of the active environment
Comma-separated list of platforms supported by the project
Path to the environment (conda compatibility)
Name of the environment (conda compatibility)
Prepended with environment's bin directory
**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
```toml theme={null}
[tasks.hello]
cmd = "echo $HELLO_WORLD"
env = { HELLO_WORLD = "Hello world!" }
[activation.env]
HELLO_WORLD = "Activate!"
```
```bash theme={null}
pixi run hello
# Output: Hello world!
```
The task environment variable wins.
### Example 2: activation.env > activation.scripts
```toml theme={null}
[activation.env]
DEBUG_MODE = "enabled"
[activation]
scripts = ["setup.sh"]
```
```bash title="setup.sh" theme={null}
export DEBUG_MODE="disabled"
```
```bash theme={null}
pixi run echo $DEBUG_MODE
# Output: enabled
```
The manifest `activation.env` wins over activation scripts.
### Example 3: activation.scripts > dependency scripts
```toml theme={null}
[activation]
scripts = ["local_setup.sh"]
[dependencies]
my-package = "*" # Has activation scripts setting LIB_PATH="/dep/lib"
```
```bash title="local_setup.sh" theme={null}
export LIB_PATH="/my/lib"
```
```bash theme={null}
pixi run echo $LIB_PATH
# Output: /my/lib
```
Local activation scripts override dependency scripts.
### Example 4: dependency scripts > outside variables
```bash theme={null}
# Outside environment
export PYTHON_PATH="/system/python"
```
```toml theme={null}
[dependencies]
python-utils = "*" # Sets PYTHON_PATH="/pixi/python"
```
```bash theme={null}
pixi run echo $PYTHON_PATH
# Output: /pixi/python
```
Dependency activation scripts override outside environment.
### Example 5: Complete Priority Chain
```toml theme={null}
[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"
```
```bash title="app_setup.sh" theme={null}
export APP_CONFIG="activation-script"
```
```bash theme={null}
# Outside environment
export APP_CONFIG="system-config"
```
```bash theme={null}
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
```bash theme={null}
# 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/`:
```bash theme={null}
tree .pixi/activation-env-v0/
```
```
.pixi/activation-env-v0/
├── activation_default.json
└── activation_lint.json
```
### Cache Contents
```json theme={null}
{
"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:
```bash theme={null}
pixi run --force-activate
pixi shell --force-activate
pixi shell-hook --force-activate
```
Or configure globally:
```toml theme={null}
[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
```bash title="~/.bashrc" theme={null}
# 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
```bash title="~/.bashrc" theme={null}
# 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
```bash title="~/.bashrc or ~/.zshrc" theme={null}
eval "$(pixi shell-hook)"
```
### Fish
```fish title="~/.config/fish/config.fish" theme={null}
pixi shell-hook | source
```
### PowerShell
```powershell title="$PROFILE" theme={null}
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
```toml theme={null}
[shell]
change-ps1 = false
```
Or via CLI:
```bash theme={null}
pixi shell --change-ps1=false
```
### Custom Prompt
The `PIXI_PROMPT` variable contains the prompt prefix:
```bash theme={null}
echo $PIXI_PROMPT
# Output: (pixi:default)
```
Use in your custom prompt:
```bash title="~/.bashrc" theme={null}
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.