Python包管理工具uv的命令大全(附核心注意事项)_Python

uv 是 rust 编写的新一代极速 python 环境/包管理工具，兼容 pip/venv 语法且速度提升 10-100 倍，以下是全场景命令汇总和避坑指南，覆盖环境创建、包管理、依赖锁定等核心场景，适配 windows/macos/linux。另外，为了便于pip用户迁移，安装包时使用uv pip install，另外也推荐使用uv add 安装依赖，uv remove卸载依赖。

一、核心命令分类汇总

1. 环境管理（venv）

命令	功能	示例	说明
uv venv	创建默认虚拟环境	uv venv	默认在当前目录生成 .venv 文件夹，自动匹配系统 python
uv venv <路径>	指定路径/名称创建环境	uv venv .venv_ct	自定义环境名（如 .venv_ct），避免同名覆盖
uv venv --python <版本>	指定 python 版本创建	uv venv .venv_311 --python 3.11	自动下载对应版本（需网络），支持 3.8/3.10/3.12 等
uv venv --system-site-packages	继承全局包	uv venv .venv --system-site-packages	共享全局已装包，适合快速复用依赖
uv venv --clear <路径>	清空并重建环境	uv venv --clear .venv	保留环境目录，删除旧依赖后重建

激活环境（windows）：

# 激活默认环境
.venv\scripts\activate
# 激活自定义环境
venv_test  \scripts\activate
# 退出环境
deactivate

2. 包安装/卸载（pip）

uv pip 完全兼容 pip 语法，且速度远快于 pip，核心命令：

命令	功能	示例	说明
uv pip install <包名>	安装单个包	uv pip install opencv-python==4.1.0	支持指定版本（==/>=/<）
uv pip install -r requirements.txt	批量安装依赖	uv pip install -r requirements.txt	极速解析并安装，自动处理依赖冲突
uv pip install .	安装本地包（setup.py/pyproject.toml）	uv pip install .	适合开发本地项目
uv pip install --editable .	可编辑模式安装	uv pip install -e .	本地代码修改即时生效，无需重新安装
uv pip uninstall <包名>	卸载包	uv pip uninstall opencv-python	加 -y 跳过确认：uv pip uninstall -y opencv-python
uv pip list	查看已装包	uv pip list	格式与 pip 一致，输出更快
uv pip show <包名>	查看包详情	uv pip show opencv-python	显示版本、路径、依赖等
uv pip freeze	导出已装包到文件	uv pip freeze > requirements.txt	兼容 pip freeze 格式
uv pip cache purge	清空下载缓存	uv pip cache purge	解决缓存导致的包版本错误

3. 依赖锁定（lock）

uv 支持生成锁文件（类似 poetry/pipenv），确保环境一致性：

命令	功能	示例	说明
uv lock	生成锁文件	uv lock	读取 pyproject.toml，生成 uv.lock
uv lock --requirements <文件>	基于 requirements.txt 锁定	uv lock --requirements requirements.txt	兼容旧版依赖文件
uv sync	按锁文件同步环境	uv sync	快速安装锁文件中的所有包，确保版本一致

4. 全局配置/工具命令

命令	功能	示例	说明
uv --version	查看 uv 版本	uv --version	验证安装是否成功
uv config get	查看全局配置	uv config get	显示镜像源、缓存路径等
uv config set <键> <值>	设置配置	uv config set registry.index-url https://pypi.tuna.tsinghua.edu.cn/simple	配置清华镜像源
uv cache dir	查看缓存目录	uv cache dir	windows 默认：c:\users\<用户名>\appdata\local\uv\cache
uv python list	查看已下载的 python 版本	uv python list	显示 uv 管理的 python 解释器
uv python install <版本>	预安装指定 python 版本	uv python install 3.10	提前下载，创建环境时无需重新下载

二、配置及运行单个脚本

初始化脚本项目
uv init --script analyze.py
添加脚本依赖
uv add pandas --script analyze.py
运行脚本（自动处理依赖）
uv run analyze.py

三、uv python命令

uv python list
#list the available python installations
uv python install
#download and install python versions
uv python upgrade
#upgrade installed python versions
uv python find
#search for a python installation
uv python pin
#pin to a specific python version
uv python dir
#show the uv python installation directory
uv python uninstall
#uninstall python versions
uv python update-shell
#ensure that the python executable directory is on the path

四、关键注意事项（避坑指南）

1. 环境创建与激活

避免在同一目录重复创建 .venv：若提示「环境已存在」，要么复用（选择现有解释器），要么改名创建（如 .venv_ct），不要直接覆盖。
windows 激活报错「禁止运行脚本」：以管理员身份打开 powershell，执行 set-executionpolicy remotesigned -scope currentuser，输入 y 确认。
建议按功能命名环境：如 .venv_ct（ct 图像处理）、.venv_ml（机器学习），便于区分。

2. 包安装兼容性

不要混用 uv pip 和 pip：同一环境中用 uv 安装后，再用 pip 可能导致依赖冲突，全程用 uv pip。

安装旧版包（如 opencv-python==4.1.0）时，若提示找不到版本：检查 python 版本兼容性（如 4.1.0 不支持 python 3.12），需指定对应 python 版本创建环境。

安装本地包时，确保目录有 pyproject.toml/setup.py，否则会报错。

3. 镜像源配置（解决下载慢）

默认使用官方 pypi，国内建议配置清华/阿里镜像：

# 临时使用（单次安装）
uv pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple

# 全局配置（永久生效）
uv config set registry.index-url https://pypi.tuna.tsinghua.edu.cn/simple

4. python 版本管理

uv 自动下载的 python 版本存储在独立目录，不影响系统 python，可通过 uv python list 查看。
创建环境时指定的 python 版本若未安装，uv 会自动下载，但需保证网络通畅（可配置国内镜像加速）。
windows 下若提示「python 版本找不到」：检查环境变量，或手动执行 uv python install <版本> 预安装。

5. 与 pycharm 集成

添加解释器时，选择「现有环境」，路径指向 <环境目录>\scripts\python.exe（windows）。
切换环境后，pycharm 可能需要几秒加载依赖，耐心等待「索引完成」。
若 pycharm 识别不到 uv 环境：重启 pycharm，或手动刷新解释器列表。

6. 缓存与清理

uv 缓存默认占空间较小，但若需清理，执行 uv pip cache purge 即可。
旧环境可直接删除文件夹（如 .venv_old），无残留（区别于 conda）。

五、常用场景速查表

场景	核心命令
快速创建 ct 算法环境（python 3.11）	uv venv .venv_ct --python 3.11
安装指定版本 opencv	uv pip install opencv-python==4.1.0
导出当前环境依赖	uv pip freeze > requirements.txt
基于依赖文件创建一致环境	uv venv .venv && uv pip install -r requirements.txt
配置国内镜像源	uv config set registry.index-url https://pypi.tuna.tsinghua.edu.cn/simple