一句话结论
- 装系统级软件(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