Getting started
Requirements
Petal requires:
- Python 3.10+
- ROS2 installed under
/opt/ros/<distro> rosdep- apt tools
uv
Install
uv tool install petal-rosTo use the colcon deps verb, install the colcon extra:
uv tool install "petal-ros[colcon]"For local development:
git clone https://github.com/matthewyjiang/petal.git
cd petal
uv tool install --editable .For one-off local runs without installing the petal command:
uv run petal --helpInitialize a workspace
Run from a ROS2 workspace root:
petal initThis creates:
petal.tomlfor declared workspace dependencies..petal/venvfor PyPI-managed packages..petal/activatefor shell activation.
Add dependencies
Apt-resolved package:
petal add numpyPyPI package:
petal add huggingfaceVersion spec:
petal add ultralytics ">=8,<9"Rosdep-resolved ROS package:
petal add cv_bridgeBy default, Petal resolves dependencies apt/ROS-first and only uses PyPI when needed. You can force a source when necessary:
petal add --apt numpy
petal add --pip some-pypi-only-packageSync and verify
petal sync
petal statuspetal status exits with code 2 when the workspace is out of sync.
Work in the environment
Open an interactive shell with ROS and the workspace venv ready:
petal shell
# Work as usual, then type exit to return to your previous shell.Petal uses bash or zsh from $SHELL (bash when unset). Override with petal shell --shell bash or --shell zsh. Your normal shell configuration loads before Petal activates the environment; no dotfiles are edited.
For one command, no activation is needed:
petal run python my_node.py
petal run ros2 launch my_package launch.py
petal run colcon buildBoth commands work from workspace subdirectories without changing your current directory. They use the existing environment and never install or sync dependencies automatically.
To activate in your current shell instead, the existing commands still work:
source <(petal activate) # bash/zsh, including from subdirectoriesOr, from the workspace root (also works in POSIX sh):
. .petal/activate