ros2env

A ROS 2 distribution environment manager for Pixi global installations.

Switch between multiple ROS 2 distributions (Humble, Jazzy, Rolling, etc.) installed via Pixi with a single command — no more manually sourcing setup scripts or juggling environment variables.

Why ros2env?

• Install once, use everywhere: Install each ROS 2 distribution once with pixi global and make it available to all your workspaces — no need to add ROS 2 as a dependency in every project's pixi.toml.
• Multiple distros, one machine: Install and manage several ROS 2 distributions side by side without conflicts.
• Clean environment switching: Activating a distribution strips stale paths and variables from a previously active distro, so you always get a clean environment.
• No system ROS install required: Pixi handles the installation; ros2env handles the environment. Works on any Linux or macOS system without needing apt or the official ROS 2 installer.
• Shell integration: A lightweight shell function wraps the CLI so rosenv activate humble just works, including tab completion.
• Pixi workspace support: Detects ROS distributions inside Pixi workspaces and can merge them with global installations for local colcon-based development.

Prerequisites

• Pixi installed
• At least one ROS 2 distribution installed via pixi global, e.g.:

  pixi global install --environment ros-humble -c robostack-staging ros-humble-desktop

Supported platforms

• Linux (x86_64, aarch64)
• macOS (Apple Silicon, Intel)

Installation

From crates.io

cargo install ros2env

Pre-built binaries (via cargo-binstall)

cargo binstall ros2env

From prefix.dev

pixi global install -c ros2env rosenv

Quick start

# 1. Set up symlinks from pixi installations to /opt/ros
rosenv setup

# 2. Add shell integration to your shell config
rosenv init zsh >> ~/.zshrc   # or bash
source ~/.zshrc

# 3. Activate a distribution
rosenv activate humble

# 4. Check status
rosenv status

# 5. Switch to another distribution
rosenv activate jazzy

# 6. Deactivate when done
rosenv deactivate

Commands

Command	Description
setup	Auto-detect Pixi ROS installations and create symlinks
list	List available distributions (--names-only, --short)
status	Show the currently active distribution and environment details
activate <distro>	Activate a ROS 2 distribution
deactivate	Deactivate the current distribution
info <distro>	Show detailed info about a distribution
init <shell>	Generate shell integration code (zsh or bash)
remove <distro>	Remove a distribution symlink
cleanup	Remove all distribution symlinks
refresh	Re-scan Pixi installations and update symlinks
doctor	Diagnose common issues with your setup
pixi activate	Activate a ROS distribution inside a Pixi workspace

Documentation

See the documentation site for the full getting started guide, commands reference, and contributing guidelines.

Build from source

cargo build --release

License

MIT