pixi global expose

Manage exposed binaries from global environments

The pixi global expose command manages which executables from global environments are exposed (made available) in your system PATH.

Usage

pixi global expose <SUBCOMMAND> [OPTIONS]

Subcommands

• add - Add exposed binaries from an environment
• remove - Remove exposed binaries from the global environment

expose add

Add exposed binaries from a global environment to your system PATH.

Usage

pixi global expose add [OPTIONS] --environment <ENV> <MAPPING>...

Arguments

MAPPING · string · required

Mapping that describes which executables are exposed.

Format:

• exposed_name=executable_name - Expose executable with custom name
• executable_name - Expose executable with same name (shorthand for executable_name=executable_name)

Multiple mappings can be specified.

pixi global expose add --environment python311 python3.11=python
pixi global expose add --environment tools ruff black
pixi global expose add -e myenv tool1=bin1 tool2=bin2

Options

--environment · string · required

The environment from which binaries should be exposed.

Short flag: -e

Examples

Expose with Custom Name

pixi global expose add --environment python311 python3.11=python python3=python

Exposes the python executable as both python3.11 and python3.

Expose with Default Name

pixi global expose add --environment tools ruff black mypy

Exposes ruff, black, and mypy using their default executable names.

Expose Single Executable

pixi global expose add --environment pytest pytest=pytest

Or simply:

pixi global expose add --environment pytest pytest

Multiple Custom Mappings

pixi global expose add --environment python311 \
  python=python3.11 \
  pip=pip3.11 \
  python3=python

Exposes multiple executables with different names.

expose remove

Remove exposed binaries from the global environment.

Usage

pixi global expose remove [OPTIONS] <EXPOSED_NAME>...

Arguments

EXPOSED_NAME · string · required

The exposed name(s) that should be removed. Multiple names can be specified.

This is the name you use to call the executable (e.g., python3.11), not the original executable name.

pixi global expose remove python3.11
pixi global expose remove ruff black mypy

The command automatically determines which environment contains each exposed name.

Examples

Remove Single Exposure

pixi global expose remove python3.11

Removes the python3.11 exposed executable.

Remove Multiple Exposures

pixi global expose remove ruff black mypy

Removes multiple exposed executables at once.

Remove All Python Exposures

pixi global expose remove python python3 python3.11 pip pip3 pip3.11

Removes all Python-related exposed executables.

How Exposure Works

Unix/macOS

Exposed executables are symlinked to ~/.pixi/bin/:

~/.pixi/bin/python3.11 -> ~/.pixi/envs/python311/bin/python
~/.pixi/bin/ruff -> ~/.pixi/envs/tools/bin/ruff

Ensure ~/.pixi/bin is in your PATH:

export PATH="$HOME/.pixi/bin:$PATH"

Windows

Exposed executables are made available through shims in %USERPROFILE%\.pixi\bin\.

Complete Examples

Set Up Python Environment with Multiple Exposures

# Install Python
pixi global install --environment python311 python=3.11

# Add multiple exposures
pixi global expose add --environment python311 \
  python3.11=python \
  python3=python \
  python=python \
  pip3.11=pip \
  pip3=pip \
  pip=pip

# Verify
which python3.11
which python3
which python

Manage Tool Exposures

# Install tools
pixi global install --environment tools ruff black mypy

# Expose with default names
pixi global expose add --environment tools ruff black mypy

# Later, remove one
pixi global expose remove mypy

# Re-expose with custom name
pixi global expose add --environment tools mypy-check=mypy

Resolve Naming Conflicts

# You have Python in two environments
pixi global install --environment python311 python=3.11
pixi global install --environment python312 python=3.12

# Expose each with version-specific names
pixi global expose add --environment python311 python3.11=python py311=python
pixi global expose add --environment python312 python3.12=python py312=python

# Set the default python
pixi global expose add --environment python312 python=python python3=python

Change Exposure After Installation

# Initial installation with auto-exposure
pixi global install --environment tools ruff

# Remove auto-exposed
pixi global expose remove ruff

# Re-expose with custom name
pixi global expose add --environment tools ruff-check=ruff

State Changes Reported

After successful expose operations:

Add Output

✅ Exposed python3.11 -> python
✅ Exposed pip3.11 -> pip
✅ Updated completions

Remove Output

✅ Removed exposure python3.11
✅ Updated completions

Troubleshooting

Executable Not Found in Environment

Error: executable 'xyz' not found in environment 'myenv'

Solution: Verify the executable exists:

pixi global list --environment myenv
# Check which executables are available

Exposed Name Already Exists

Error: exposed name 'python' already exists

Solution: Remove the existing exposure first:

pixi global expose remove python
pixi global expose add --environment newenv python=python

Environment Not Found

Error: Environment 'xyz' not found

Solution: Check environment name:

pixi global list
pixi global expose add --environment correct-name executable

Exposed Binary Not in PATH

After exposing, executable not found:

Solution: Ensure ~/.pixi/bin is in your PATH:

# Unix/macOS - add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.pixi/bin:$PATH"

# Reload shell
source ~/.bashrc

# Verify
echo $PATH
which exposed-binary

Exposure Removed but Binary Still Works

Binary might be exposed from another environment or installed separately:

# Check all exposures
pixi global list

# Check which binary is being used
which binary-name

Error Handling

If an expose operation fails, pixi automatically reverts changes to maintain consistency.

On error:

1. Changes to the environment are rolled back
2. Symlinks/shims are restored to previous state
3. Error details are reported

Config Options

--tls-no-verify · boolean

Disable TLS certificate verification.

--auth-file · string

Path to authentication file.

pixi global expose add --environment myenv tool --tls-no-verify

Best Practices

Use Version-Specific Names

pixi global expose add --environment python311 \
  python3.11=python \
  python3=python \
  python=python

This prevents conflicts when multiple versions are installed.

Document Custom Mappings

Keep track of custom exposures:

# View current exposures
pixi global list

# Or check manifest
pixi global edit

Remove Unused Exposures

Clean up exposures you no longer need:

pixi global list
pixi global expose remove unused-tool1 unused-tool2

See Also

• pixi global install - Install global environments (with auto-exposure)
• pixi global add - Add packages and expose executables
• pixi global list - View exposed executables
• pixi global remove - Remove packages from environments