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 --help, all discovered extensions are automatically listed in the "Available Extensions" section, making them easily discoverable alongside built-in commands.

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 --help just like built-in commands

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#

Choose a descriptive name: Your extension should be named pixi-{command} where {command} clearly describes its functionality.
Create the executable: Extensions can be written in any language (Rust, Python, shell scripts, etc.) as long as they produce an executable binary.
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 --help to see all available extensions
Community: Join our Discord for discussions and support