pixi-ros 0.1.2

Pixi extension for ROS package management

pixi-ros

Bridge your ROS workspace to the modern conda/Pixi ecosystem

pixi-ros helps ROS developers transition from rosdep to Pixi for package management. It automatically reads your ROS workspace's package.xml files and generates a pixi.toml manifest with all dependencies resolved from conda channels (primarily robostack).

Why pixi-ros?

If you're a ROS developer, you're probably familiar with rosdep managing dependencies. pixi-ros gives you access to a more modern package management ecosystem:

• Reproducible environments: Lock files ensure everyone on your team has identical dependencies
• Cross-platform: Works seamlessly on Linux, macOS, and Windows
• Fast and reliable: Uses rattler (Rust implementation of conda) for speed
• No system dependencies: Everything isolated in project environments

Quick Start

Installation

Install pixi first if you haven't already:

curl -fsSL https://pixi.sh/install.sh | bash

Or follow instructions at https://pixi.sh/latest/installation/

Install pixi-ros globally using pixi:

pixi global install pixi-ros

Initialize Your ROS Workspace

Navigate to your ROS workspace and run:

pixi-ros init --distro humble

This will:

1. Discover all ROS packages in your workspace (by finding package.xml files)
2. Read dependencies from each package.xml
3. Map ROS package names to conda packages
4. Generate/update pixi.toml with proper channels and dependencies
5. Check package availability and warn about missing packages
6. Create helpful build/test/clean tasks

Install and Build

After initialization, use standard pixi commands:

# Install all dependencies
pixi install

# Build your workspace
pixi run build

# Run tests
pixi run test

# Activate environment for direct ROS commands
pixi shell

How It Works

Dependency Mapping

pixi-ros reads all dependency types from package.xml files. It then does a best effort mapping of ROS package names to conda packages.

• ROS packages: ros-{distro}-{package} from robostack channels (e.g., ros-humble-rclcpp)
• System packages: Mapped to conda-forge equivalents (e.g., cmake, eigen)

After the mapping, it validates package availability in the configured channels. This starts a connection with https://prefix.dev to check if packages exist.

Example

Given a package.xml with:

<depend>rclcpp</depend>
<build_depend>ament_cmake</build_depend>
<exec_depend>std_msgs</exec_depend>

pixi-ros init --distro humble generates a pixi.toml with:

[dependencies]
ros-humble-ament-cmake = "*"
ros-humble-rclcpp = "*"
ros-humble-std-msgs = "*"

Supported ROS Distributions

• ROS 2 Humble: https://prefix.dev/robostack-humble
• ROS 2 Iron: https://prefix.dev/robostack-iron
• ROS 2 Jazzy: https://prefix.dev/robostack-jazzy
• ROS 2 Rolling: https://prefix.dev/robostack-rolling

Command Reference

pixi-ros init

Initialize or update a ROS workspace's pixi.toml.

pixi-ros init --distro <ros_distro>
pixi-ros init

Options:

• --distro, -d: ROS distribution (optional)

What it does:

• Scans workspace for package.xml files
• Reads all dependency types (build, exec, test)
• Maps ROS dependencies to conda packages
• Configures robostack channels
• Checks package availability
• Creates build tasks using colcon
• Generates helpful README_PIXI.md

Running multiple times: The command is idempotent - you can run it multiple times to update dependencies as your workspace changes.

Philosophy

pixi-ros aims to be a quick gateway drug. It:

• Respects existing ROS conventions (package.xml as source of truth)
• Uses standard ROS build tools (colcon)
• Focuses only on dependency management and environment setup
• Doesn't replace ros2 CLI or other ROS tooling
• Should eventually become unnecessary as the ecosystem matures

Think of it as a "gateway" to help ROS developers benefit from modern package management while keeping familiar workflows.

Project Structure

After initialization, your workspace will have:

workspace/
├── src/                    # Your ROS packages
│   └── my_package/
│       ├── package.xml    # ROS package manifest (source of truth)
│       └── ...
├── pixi.toml              # Generated pixi manifest
├── pixi.lock              # Locked dependencies (commit this!)
└── README_PIXI.md         # Generated usage guide

Troubleshooting

Package Not Found

If pixi-ros marks packages as "NOT FOUND":

1. Check if the package exists in robostack: https://prefix.dev/channels/robostack-{distro}
2. Check for typos in package.xml
3. Some packages may have different names - check mapping files
4. Consider adding the package to your workspace instead of depending on it

Different Package Names

pixi-ros includes mapping files for system packages (e.g., cmake → cmake, eigen → eigen). You can override mappings by creating pixi-ros/*.yaml files in your workspace or ~/.pixi-ros/.

Platform-Specific Issues

Some packages have platform-specific mappings. pixi-ros handles this automatically, but you can test different platforms using the internal API with platform_override.

Contributing

Contributions welcome! Feel free to open issues or PRs on GitHub.

Learn More

• Pixi: https://pixi.sh
• RoboStack: https://robostack.org/
• Conda: https://docs.conda.io/
• ROS 2: https://docs.ros.org/

Disclaimer

This tool is build with heavy use of AI assistance and is under active development. Please report issues or contribute on GitHub!

I (Ruben) hope pixi-ros can die ASAP, as all of the workflows this tool provides should ideally be native to Pixi itself. But until then, I hope this initialization tool helps you get started!