colcon-uv

A colcon extension for building and testing Python packages that use uv for dependency management.

Intended, but not limited, to use with ROS 2. This extension provides a modern alternative to traditional setuptools-based or even poetry-based Python package management in ROS environments.

⚠️ Experimental: This project is in early development. Testing, feedback, and contributions are welcome!

Features

• Fast Dependency Management: Leverages UV's lightning-fast dependency resolution and installation
• Modern Python Packaging: Support for pyproject.toml-based packages following PEP 517/518 standards
• ROS Integration: Seamless integration with colcon build system and ROS package management
• Dependency Isolation: Prevents dependency conflicts between packages

Installation

Important: This extension must be installed in the same environment as colcon to be discoverable by colcon's plugin system. Typically this means system-wide installation.

Install from PyPi (last tagged version)

# Using pip
pip install colcon-uv --break-system-packages

# Using uv
uv pip install --system --break-system-packages colcon-uv

Install from GitHub (development version)

# Using pip
pip install git+https://github.com/nzlz/colcon-uv.git#subdirectory=colcon_uv --break-system-packages

# Using uv
uv pip install --system --break-system-packages git+https://github.com/nzlz/colcon-uv.git#subdirectory=colcon_uv

Quick Start

For practical examples, see the test examples in this repository:

• ament_cmake for C++/Python hybrid packages tests/examples/uv_ament_cmake_example
• ament_python for pure Python packages tests/examples/uv_ament_python_example

Usage

Automatic Dependency Installation

When you run colcon build, dependencies are automatically installed using UV. No additional steps required!

# Dependencies are automatically installed during build
colcon build --packages-select my_package

Manual Dependency Installation (Optional)

Similar to rosdep install, you can optionally install dependencies standalone before building:

# Install dependencies for all packages in src/
colcon uv install

Note: This step is optional since colcon build automatically handles dependency installation. Use this when you want to pre-install dependencies or troubleshoot dependency issues separately from the build process.

Configuration

Refer to colcon_uv/README.md

References

This project is inspired by and builds upon:

• colcon-poetry-ros - Poetry integration for ROS packages
• colcon-ros - Experimental ROS support for colcon
• uv - An extremely fast Python package installer and resolver

Acknowledgments

Built with the assistance of Cursor - AI-powered code editor.