Python包管理工具uv的命令大全(附核心注意事项)
作者：痛&快乐着
uv是Rust编写的新一代极速Python环境/包管理工具,兼容pip/venv语法且速度提升10-100倍,以下是全场景命令汇总和避坑指南,希望对大家有所帮助
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 |
六、总结
uv 核心优势是「极速+兼容」：uv venv 替代 python -m venv，uv pip 替代 pip，语法完全兼容且速度大幅提升；
环境管理关键是「自定义命名+避免覆盖」，包管理需「全程用 uv pip、不混用 pip」；
国内使用必配镜像源，Windows 需解决 PowerShell 执行策略问题，与 PyCharm 集成时指向正确的 Python 可执行文件。
以上就是Python包管理工具uv的命令大全(附核心注意事项)的详细内容，更多关于Python uv命令的资料请关注脚本之家其它相关文章！