Pixi Extensions

Pixi allows you to extend its functionality with various extensions. When executing e.g. pixi diff, Pixi will search for the executable pixi-diff in your PATH and in your pixi global directories. Then it will execute it by passing any additional arguments to it.

How Extensions Work

Pixi extensions are standalone executables that follow a simple naming convention: they must be named pixi-{command} where {command} is the name of the subcommand you want to add. When you run pixi {command}, Pixi will automatically discover and execute the corresponding pixi-{command} executable.

For example:

• pixi diff → looks for pixi-diff executable
• pixi pack → looks for pixi-pack executable
• pixi deploy → looks for pixi-deploy executable

Extension Discovery

Pixi discovers extensions by searching for pixi-* executables in the following locations, in order:

1. PATH Environment Variable

Pixi searches all directories in your PATH environment variable for executables with the pixi- prefix.

2. pixi global Directories

Pixi also searches in directories managed by pixi global, which allows for organized extension management without cluttering your system PATH.

When you run pixi --list, all discovered extensions are automatically listed alongside all built-in commands, making the commands easily discoverable.

Installing Extensions

Using pixi global (Recommended)

The easiest way to install Pixi extensions is using pixi global install:

# Install a single extension
pixi global install pixi-pack

# Install multiple extensions at once
pixi global install pixi-pack pixi-diff

This approach has several advantages:

• Isolated environments: Each extension gets its own environment, preventing dependency conflicts
• Automatic discovery: Extensions are automatically found by Pixi without modifying PATH
• Easy management: Use pixi global list and pixi global remove to manage extensions
• Consistent experience: Extensions appear in pixi --list with all the built-in commands, just like how Cargo handles it

Manual Installation

You can also install extensions manually by placing the executable in any directory in your PATH:

# Download or build the extension
curl -L https://github.com/user/pixi-myext/releases/download/v1.0.0/pixi-myext -o pixi-myext
chmod +x pixi-myext
mv pixi-myext ~/.local/bin/

Contributing Extensions

Creating an Extension

1. Choose a descriptive name: Your extension should be named pixi-{command} where {command} clearly describes its functionality.

2. Create the executable: Extensions can be written in any language (Rust, Python, shell scripts, etc.) as long as they produce an executable binary.

3. Handle arguments: Extensions receive all arguments passed after the command name.

Example: Simple Python Extension

#!/usr/bin/env python3
import sys

def main():
    name = sys.argv[1] if len(sys.argv) > 1 else "World"
    print(f"Hello, {name}!")

if __name__ == "__main__":
    main()

Save this as pixi-hello, make it executable (chmod +x pixi-hello), and place it in your PATH.

Usage: pixi hello Alice outputs Hello, Alice!

Best Practices

• Use standard argument parsing: Libraries like clap (Rust) or argparse (Python) provide consistent behavior
• Support --help: Users expect this standard flag
• Follow UNIX conventions: Use exit code 0 for success, non-zero for errors
• Work with Pixi environments: Extensions should respect Pixi's environment management

Command Suggestions

Pixi includes intelligent command suggestions powered by string similarity. If you mistype a command name, Pixi will suggest the closest match from both built-in commands and available extensions:

$ pixi pck
error: unrecognized subcommand 'pck`
tip: a similar subcommand exists: 'pack'

This works for both built-in commands and any extensions you have installed, making extension discovery seamless.

Getting Help

• List available extensions: Run pixi --list to see all available extensions
• Community: Join our Discord for discussions and support

See Also

• Pixi Diff - Compare lock files and environments
• Pixi Inject - Inject dependencies into existing environments
• Pixi Skills - Manage and install coding agent skills across LLM backends
• Global Tools - Managing global tool installations