一个在uv 虚拟环境中创建运行ros2 python功能包的方法

介绍

一个在uv 虚拟环境中创建运行ros2 python功能包的方法

原理

1. 创建虚拟环境时要把系统的python环境导入到虚拟环境,rclpy、colcon 等都在系统环境中
2. 虚拟环境的python版本建议与系统版本相同，避免依赖错误
3. ros2 run 运行时需要以虚拟环境内的python 解释器运行，而不是系统的。

uv 可以指定系统 Python 解释器路径，导入系统的python包

uv venv --python [path] --system-site-packages

使用 Conda 虚拟环境管理和运行 ROS2 python
这篇文章提到ros2 run 命令运行 Python 文件时，会执行一个位于 install/your_packages_name/lib/your_packages_name/the_entries_name 的脚本。
该脚本的第一行是 shebangs，指定了用于执行代码的 Python, 由colcon自动设置。
如果你使用 colcon来编译包，第一行通常是默认值：#!/usr/bin/python 此时系统全局python会被用来运行包；
如果使用 python -m colcon来编译，则会使用虚拟环境下的python库运行

流程

系统已经安装ros2、uv

创建默认功能包

mkdir uvros_ws/src -p
cd uvros_ws/src
source /opt/ros/humble/setup.bash
ros2 pkg create --build-type ament_python pkg_python --node-name uvpy --license Apache-2.0 # Python

查看系统python解释器路径

$ whereis python3
python3: /usr/bin/python3 /usr/lib/python3 /etc/python3 /usr/share/python3 /usr/share/man/man1/python3.1.gz

建虚拟环境

cd uvros_ws/
uv venv --python /usr/bin/python3 --system-site-packages
source .venv/bin/activate

虚拟环境安装一个python包测试

$uv pip install emoji

$uv run python3
Python 3.10.12 (main, Mar  3 2026, 11:56:32) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import emoji
>>> print(emoji.emojize('Python is :thumbs_up:'))
Python is 👍

python脚本中导入emoji 库

vim src/pkg_python/pkg_python/uvpy.py

import sys

def main():
    print('Hi from pkg_python.')
    print(sys.executable)

    import emoji
    print(emoji.emojize('Python is :thumbs_up:'))
    print(emoji.emojize("Python is fun :red_heart:"))
    print(emoji.emojize("Python is fun :red_heart:", variant="emoji_type"))
    print(emoji.demojize('Python is 👍'))
    print(emoji.is_emoji("👍"))

if __name__ == '__main__':
    main()

此时uv 环境直接uv run 是可以正常执行的，

$ uv run src/pkg_python/pkg_python/uvpy.py
Hi from pkg_python.
/home/ros/uvros_ws/.venv/bin/python3
Python is 👍
Python is fun ❤️
Python is fun ❤️
Python is :thumbs_up:
True

但是直接colcon build 使用ros2 run 会找不到emoji：No module named 'emoji'

使用虚拟环境colcon build

创建虚拟环境时，--system-site-packages把系统colcon导入到了虚拟环境
使用uv run python -m colcon build 编译

uv run python -m colcon build --packages-select pkg_python --symlink-install
# 运行
source install/setup.bash
ros2 run pkg_python uvpy 

必须使用--symlink-install 参数，否则会提示：No executable found

$ uv run python -m colcon build --packages-select pkg_python --symlink-install
Starting >>> pkg_python
Finished <<< pkg_python [0.67s]

Summary: 1 package finished [0.83s]
$ source install/setup.bash
$ ros2 run pkg_python uvpy 
Hi from pkg_python.
/home/ros/uvros_ws/.venv/bin/python3
Python is 👍
Python is fun ❤️
Python is fun ❤️
Python is :thumbs_up:
True

理论上你可以为每个功能包创建一个虚拟环境