一句话结论
- 装系统级软件（C/CUDA、驱动、编译链） → 用
apt - 纯 Python 项目/虚拟环境/依赖锁文件 → 用
uv；它比apt里的 python3-xxx 新、快、隔离，但不能装非 Python 组件
下面给你展开对比，按“能干什么、不能干什么、该什么时候用”三个维度说清楚。
1. 能干什么
| 场景 | apt（Debian 系） | uv（Rust 写的 Py 包管理器） |
|---|---|---|
| 装系统库/编译器/CUDA/驱动 | ✅ 本职 | ❌ 完全干不了 |
| 装 Debian 打好的 python3-xxx | ✅ 仓库里都有 | ❌ 不管系统包 |
| 创建 Python 虚拟环境 | ❌ 需额外用 venv/virtualenv | ✅ 一行 uv venv |
| 装 PyPI 上的包 | ❌ 只能 pip 补 | ✅ 比 pip 快 10–100 倍，自带缓存与锁文件 |
| 多版本 Python 并存 | ❌ 需 pyenv/源码 | ✅ uv python install 3.12 一键装官方解释器 |
| 依赖解析 & 锁版本 | ❌ 无 | ✅ 生成 uv.lock，CI 可 100 % 复现 |
2. 不能干什么
- apt 局限性
– 带的 Python 包版本旧，更新慢；不能锁版本；无法跨项目隔离。 - uv 局限性
– 只认识 PyPI 轮子；遇到 CUDA、MKL、R、C++ 等非 Python 依赖时直接抓瞎，需要先用apt/brew装好系统库，再用uv装 Python 部分 。
3. 什么时候选哪个
| 需求 | 推荐命令 | 原因 |
|---|---|---|
| 先装显卡驱动、CUDA、编译链 | sudo apt install nvidia-cuda-toolkit build-essential |
系统层只有 apt 能做 |
| 起一个新 Python Web/AI 项目 | uv venv && uv add torch pandas |
快、隔离、自动写锁文件 |
| 跑开源项目带 requirements.txt | uv pip install -r requirements.txt |
速度比 pip 快一个量级 |
| 需要 Python 3.11/3.12 而系统只有 3.10 | uv python install 3.11 |
官方解释器一键装，无需 pyenv |
| 服务器上线部署，要 100 % 复现 | uv sync --production |
按锁文件精确还原，CI 友好 |
| 需要同时装 R、OpenCV C++ 头文件 | sudo apt install r-base libopencv-dev |
uv 装不了这些非 Python 包 |
4. 混合打法（最佳实践）
- 系统层先
apt把驱动、编译器、非 Python 依赖装好。 - 项目层用
uv管理 Python 版本与 PyPI 依赖；uv.lock进仓库，团队/CI 统一uv sync即可。
这样既享有 apt 的系统级能力，又拿到 uv 的极速与隔离，互不冲突。
下面给出一条“从零到跑通”的最简路径，全部用 uv 完成，不再碰系统 pip 和 sudo。
（假设你已经在 PC 上装好了 uv 本身，没装的话先 curl -LsSf https://astral.sh/uv/install.sh | sh）
- 新建项目目录并一次性完成“建环境 + 装包”
# 1. 建文件夹
mkdir xgo_demo && cd xgo_demo# 2. 用 uv 同时完成：创建虚拟环境、安装 Python 3.11、装 xgo-pythonlib
# （Python 版本可换成 3.10/3.12，只要 XGO 官方支持）
uv init --python 3.11 # 生成 pyproject.toml
uv add xgo-pythonlib # 自动下载解释器、建 .venv、装包并写锁文件
执行完你会看到目录里多了
.venv/ —— 虚拟环境
uv.lock —— 精确版本锁
pyproject.toml —— 项目元数据
- 验证包已装好
uv run python -c "import xgo, xgoedu; print('OK')"
只要打印 OK 就说明 xgo-pythonlib 里的 xgolib.py / xgoedu.py 已就绪。
- 运行官方例程
把官方文档里的 demo 代码（例如xgo.move_forward(2)之类）保存成demo.py，然后
uv run python demo.py
uv run 会自动激活虚拟环境，不用你手动 source .venv/bin/activate。
- 后续常用命令备忘
- 再装别的 PyPI 包
uv add numpy opencv-python - 升级 XGO 库
uv add --upgrade xgo-pythonlib - 进交互调试
uv run ipython# 先uv add ipython即可 - 锁版本进仓库
git add uv.lock pyproject.toml
- 如果官方 wheel 装不上
XGO 目前只提供了xgo-pythonlib-*.whl，没有源码包；uv默认先找 wheel，找不到才会尝试编译，所以基本和pip行为一致。
万一出现ERROR: Could not find a version that satisfies the requirement xgo-pythonlib，多半是 Python 版本不兼容，把上面--python 3.11换成 3.9/3.10 再试即可。
一句话总结
uv init --python 3.11
uv add xgo-pythonlib
uv run python demo.py
三步到位，系统 pip 和 sudo 完全不再需要。
在树莓派（Raspberry Pi OS）上，只要打下面任意一条命令，就能立刻看到当前用户的 PATH 变量里到底有哪些目录：
- 最直接
echo $PATH
输出示例
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/local/games:/usr/games:/home/pi/.local/bin:/home/pi/.cargo/bin
用冒号 : 隔开的就是所有已加入 PATH 的目录。
- 想每个目录单独一行看
tr ':' '\n' <<< "$PATH"
结果
/usr/local/sbin
/usr/local/bin
...
/home/pi/.cargo/bin
- 想看系统级默认 PATH（登录 shell 还没加载用户配置时的值）
# 新建一个干净 shell，不读 ~/.bashrc
env -i bash -c 'echo $PATH'
- 忘了自己把 uv 放哪了？直接搜可执行文件
which uv # 返回第一条命中，例如 /home/pi/.cargo/bin/uv
command -v uv # 功能同上，更通用
- 想确认某个目录是否真的在 PATH 里
# 例：检查 ~/.local/bin 是否已加入
[[ ":$PATH:" == *":$HOME/.local/bin:"* ]] && echo "已加入" || echo "未加入"
把上面任何一条粘到终端回车即可，无需 sudo。
把 uv 放到 已经出现在 PATH 里的、当前用户可写 的目录即可。
从你贴出的结果看，最合适、最惯用的就是：
/home/pi/.local/bin
理由
- 已经在 PATH 末尾（
/home/pi/.local/bin出现与否没关系，只要你在~/.profile或~/.bashrc里追加一次即可）。 - 无需
sudo，普通用户就能写。 - 系统升级不会覆盖。
一步完成（假设你现在就在解压出来的目录）：
# 1. 确保目录存在
mkdir -p ~/.local/bin# 2. 拷贝（或移动）可执行文件
cp uv ~/.local/bin/ # 或 mv uv ~/.local/bin/# 3. 加执行权限（下载 tar.gz 一般已带，可再确认）
chmod +x ~/.local/bin/uv# 4. 验证
uv --version # 看到 0.x.y 即成功
如果第 4 步报 “command not found”，说明 ~/.local/bin 还没进 PATH，手动加一次：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
再执行 uv --version 就应该正常了。
你的树莓派系统（Raspberry Pi OS ≥12）已经启用了 PEP-668 保护，禁止用系统 pip 再装任何包。
因此 pip install uv 被直接拒绝，而且 uv 官方也没给 apt 仓库，所以只能用“官方单文件二进制”方式安装，与系统 Python 彻底无关。
下面给出两条最简路径，30 秒搞定。
路径 A：一键脚本（自动装到 ~/.cargo/bin，无需 sudo）
# 下载并运行官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh
# 脚本会把 uv 放到 ~/.cargo/bin，顺便帮你写入 PATH
source ~/.cargo/env # 立即生效
uv --version # 验证，能看到 0.x.y 即成功
路径 B：手动下载单文件（适合离线或网络差）
# 1. 查看树莓派 CPU 架构
uname -m
# 输出 aarch64 → 用 arm64 版本；输出 armv7l → 用 armv7 版本# 2. 下载对应二进制（以 aarch64 为例）
wget https://github.com/astral-sh/uv/releases/latest/download/uv-aarch64-unknown-linux-gnu.tar.gz
tar -xzf uv-aarch64-unknown-linux-gnu.tar.gz
chmod +x uv
mv uv ~/.local/bin/ # 或任何已在 PATH 的目录
uv --version
然后就可以回到项目目录，用 uv 创建虚拟环境并安装 XGO 库了：
cd ~/Desktop/xgodemo
uv init --python 3.11 # 自动下载解释器 & 建 .venv
uv add xgo-pythonlib
uv run python -c "import xgo; print('OK')"
常见坑
- 如果
~/.cargo/bin或~/.local/bin不在 PATH，把
export PATH="$HOME/.cargo/bin:$PATH"写进~/.bashrc或~/.zshrc再source一次即可。 - 树莓派 32 位系统（armv7l）请下载
uv-armv7-unknown-linux-gnueabihf.tar.gz，64 位用aarch64版。
装完 uv 以后，全程不再需要 sudo，也不再触碰系统 Python，PEP-668 报错自然消失。
一句话答案
- 删环境：直接
rm -rf .venv即可； - 备份/还原：把
pyproject.toml+uv.lock拷走，在新目录uv sync就 100 % 原样恢复。
下面给出完整操作与“换路径再加载”的示例。
- 当前项目里导出“配置快照”
cd ~/Desktop/xgodemo # 旧项目根目录
# 已经存在
# pyproject.toml (含 [project] dependencies = ["xgo-pythonlib", "pyserial", ...])
# uv.lock (精确版本锁)
# 如需手动再生成锁文件
uv lock
- 删除虚拟环境（可选，不占空间）
rm -rf .venv
整个环境就没了，但 只要保留上面两个文件，随时能重建。
- 把“配置”拷到新位置
# 例：拷到 U 盘或另一台机器
cp pyproject.toml uv.lock /media/usb/
- 在新目录一键还原
mkdir ~/new_workspace && cd ~/new_workspace
cp /media/usb/{pyproject.toml,uv.lock} . # 拿到两份文件
uv sync # 根据 lock 重建 .venv，包装到一模一样
uv sync 会自动：
- 下载相同 Python 版本（
pyproject.toml里requires-python字段） - 按
uv.lock里哈希装回 完全相同的二进制 wheel - 生成新的
.venv，无需再uv add任何包。
- 运行代码
uv run python your_script.py
与旧环境毫无区别。
- 只想“临时指定环境路径”而不是复制？
uv支持把虚拟环境放在任意位置，但 依旧以项目根目录的pyproject.toml为准：
# 在旧目录外建个独立环境
uv venv /opt/venvs/xgo
# 以后每次手动指定
uv run --python /opt/venvs/xgo/bin/python your_script.py
不过官方推荐 “一个项目一个 .venv”，换机器就拷两份文件再 uv sync，最干净。
总结
- 删除：
rm -rf .venv - 备份：
cp pyproject.toml uv.lock <备份路径> - 还原/迁移：
cd <新目录> && uv sync
