Proposal: Adopt uv as the standard Python package manager for Autoware via colcon-uv

[hakuturu583]

Motivation

As Autoware's Python ecosystem grows — from neural-network-based planners to 3DGS (3D Gaussian Splatting) simulators — we increasingly need a fast, reproducible, and isolation-aware Python package manager. The current approach mixes pip, pipx, manual venv, and apt-installed python3-* packages, which creates several pain points:

1. Slow dependency resolution: Installing heavy ML stacks (PyTorch, transformers, flash-attn, TensorRT bindings) via pip is slow. uv is 10-100x faster than pip for resolution and installation.

2. Fragile isolation: Today, only acados uses a dedicated venv (/opt/acados/.venv). New Python-heavy packages (3DGS renderers, Alpamayo VLM planner) need their own isolated environments without conflicting with each other or system ROS packages.

3. No standard for Python-native ROS 2 packages: ROS 2's default ament_python build type relies on legacy setup.py/setup.cfg. Modern Python packages use pyproject.toml with PEP 517/518 build backends (e.g., uv_build, hatchling). We lack a bridge between colcon build and these modern packages.

Proposal

Adopt uv as the standard Python package manager for Autoware, integrated through colcon-uv.

1. colcon-uv: Bridging uv and ROS 2

colcon-uv is a colcon extension developed by TIER IV that enables building and testing uv-managed Python packages within colcon build workflows. It:

• Identifies packages with [tool.colcon-uv-ros] in their pyproject.toml
• Creates per-package venvs with --system-site-packages (so rclpy, geometry_msgs, etc. remain accessible)
• Resolves dependencies via uv pip install (fast!)
• Generates ROS environment hooks and executable symlinks for ros2 run / ros2 launch compatibility
• Supports [tool.uv] overrides and PEP 735 dependency groups

Example pyproject.toml for a colcon-uv package:

[build-system]
requires = ["uv_build>=0.7"]
build-backend = "uv_build"

[project]
name = "my_ros_package"
requires-python = ">=3.10"
dependencies = ["torch>=2.8", "transformers>=4.57"]

[tool.colcon-uv-ros.data-files]
"share/ament_index/resource_index/packages" = ["resource/{package_name}"]
"share/{package_name}" = ["package.xml", "launch/", "config/"]

[tool.colcon-uv-ros.dependencies]
depend = ["rclpy", "sensor_msgs", "geometry_msgs"]

2. Concrete Use Case: 3DGS-Based Simulator (SplatSim)

We are working on integrating a 3D Gaussian Splatting renderer as a camera simulator for Autoware (feat/splatsim branch). This package:

• Has heavy Python dependencies (PyTorch, spconv, diff-gaussian-rasterization, etc.)
• Needs CUDA-aware builds with specific version pinning
• Must coexist with other Python packages in the workspace without conflicts
• Benefits enormously from uv's fast resolution when rebuilding environments

colcon-uv is already being installed in this branch (ansible/roles/ros2_dev_tools/tasks/main.yaml) to manage this integration.

3. Concrete Use Case: alpamayo-autoware (End-to-End VLM Planner)

alpamayo-autoware wraps NVIDIA's Alpamayo 1.5 vision-language model as a ROS 2 node for end-to-end trajectory planning. Its Python dependency stack is substantial:

• torch==2.8.0, transformers==4.57.1, flash-attn, tensorrt, physical_ai_av
• The core library (alpamayo1_5/) already uses uv_build as its build backend and uv sync / uv venv for environment management
• The ROS wrapper (alpamayo_ros/) currently uses ament_python but could be unified under colcon-uv

With colcon-uv, the entire alpamayo-autoware repository could be built with a single colcon build, resolving both pip-managed ML dependencies and ROS system packages seamlessly.

4. Improving Existing venv Management (acados)

The current acados Ansible role manually manages a Python virtual environment through a multi-step imperative process:

# Current approach (ansible/roles/acados/tasks/main.yaml)
- python3 -m venv /opt/acados/.venv          # 1. Create venv
- .venv/bin/pip install --upgrade pip          # 2. Upgrade pip
- .venv/bin/pip install casadi sympy           # 3. Install dependencies
- .venv/bin/pip install -e acados_template     # 4. Install acados Python interface (editable)

This works, but has several drawbacks:

• No lockfile: casadi and sympy versions are unpinned — builds are not reproducible across time
• No dependency resolution caching: Every Docker image rebuild or dev environment setup re-resolves and re-downloads everything from scratch
• Imperative Ansible tasks: 4 sequential shell commands that are fragile and hard to maintain
• Isolated from colcon: The venv at /opt/acados/.venv is invisible to the ROS 2 build system, requiring manual .bashrc environment variable injection (CMAKE_PREFIX_PATH, LD_LIBRARY_PATH, ACADOS_SOURCE_DIR)

With uv + colcon-uv, this could become a declarative pyproject.toml:

[build-system]
requires = ["uv_build>=0.7"]
build-backend = "uv_build"

[project]
name = "acados_template"
requires-python = ">=3.10"
dependencies = ["casadi", "sympy"]

[tool.colcon-uv-ros.dependencies]
depend = []  # No ROS dependencies for acados

Benefits:

• uv.lock ensures reproducible builds with exact pinned versions
• uv caching makes reinstallation near-instant (seconds vs minutes)
• Single colcon build handles venv creation, dependency resolution, and installation
• No manual .bashrc hacks — colcon environment hooks handle paths automatically

Benefits Summary

Aspect	Current State	With uv + colcon-uv
Resolution speed	pip (minutes for large stacks)	uv (seconds)
Isolation	Manual venv (acados only)	Per-package venvs, automatic
ROS 2 compatibility	ament_python + setup.py	colcon-uv + pyproject.toml (PEP 517)
Reproducibility	No lockfiles	uv.lock per package
ML stack management	Ad-hoc pip installs	Declarative pyproject.toml with overrides

Migration Path

1. Phase 1: Install colcon-uv in dev tooling and migrate acados venv setup to colcon-uv-managed pyproject.toml. Validate that the new declarative approach reproduces the current behavior.
2. Beyond: With colcon-uv in place, Python-heavy packages such as 3DGS-based simulators (SplatSim) and end-to-end VLM planners (alpamayo-autoware) can be integrated into the Autoware workspace via a single colcon build, with fast dependency resolution, per-package isolation, and reproducible lockfiles out of the box.

Questions for Discussion

• Are there concerns about adding uv as a build-time dependency?
• Should we aim for colcon-uv to be upstreamed into colcon's official extension set?
• How should we handle the Python 3.10 (Humble) vs 3.12 (Jazzy) split for packages like alpamayo that need >=3.11 for some features?

Looking forward to hearing the community's thoughts!

[VRichardJP]

Does colcon-uv generate valid ROS2 packages? can you do everything that you could do with the ugly setup.py? like import messages or code from another packaet (made with setup.py or uv), etc?

[hakuturu583]

Does colcon-uv generate valid ROS2 packages?

If we define a valid ROS 2 package as one that can be built using colcon build, then the answer is yes.

can you do everything that you could do with the ugly setup.py? like import messages or code from another packaet (made with setup.py or uv), etc?

Yes, colcon uv supports resolving ROS package dependency.

[VRichardJP]

How much has this package been tested?

I have quickly tested it on some of my uv projects, and I face a few annoying issues. Notably:

• it seems like explicit conflicts are ignored. In my case, I have several conflicting groups, but it looks like colcon-uv is trying to install all groups
• similarly, default group is ignored

[hakuturu583]

How much has this package been tested?

Is "this package" means colcon-uv?.

it seems like explicit conflicts are ignored. In my case, I have several conflicting groups, but it looks like colcon-uv is trying to install all groups
similarly, default group is ignored

I understand these issues.
Please use this fork.
I am now fork and maintain this package.

[hakuturu583]

Does anyone have any thoughts on this matter?
I’d also welcome any alternative suggestions.

[xmfcx]

I'd love to have uv support in Autoware project!
You forked https://github.com/nzlz/colcon-uv into https://github.com/tier4/colcon-uv because the owners were not responding to the raised PRs.

• https://pypi.org/project/colcon-uv/ exists.

But it is not part of apt packages like python3-colcon-* from packages.ros.org

I'd suggest:

1. Hard fork it under a different name like colcon-uv-awf (or something like this)
2. Publish it to https://pypi.org
3. Release it to http://packages.ros.org/ if possible or some other apt repository. (I didn't check how packages like python3-colcon-core are present in packages.ros.org ) This way we can avoid the destructive --break-system-packages