这才是 2026 年该用的 Python 项目管理方式:UV 全面上手

引言

你是不是也遇到过这些烦恼：用 pip 安装依赖慢到怀疑人生，venv 创建环境还要手动激活，一不小心就把全局 Python 搞得一团糟？ 如果你还在用传统方式管理 Python 环境，是时候认识一下 UV 了。 UV 是一个用 Rust 编写的极速 Python 包管理器，由著名工具 ruff 的作者开发。它的核心卖点只有一个字——快。有多快？官方数据显示，UV 安装依赖的速比 pip 快 10 到 100 倍，几乎是秒级完成。 但这还不是全部。UV 不仅能替代 pip，还能替代 pip-tools、virtualenv，甚至部分场景下可以替代 poetry。它把虚拟环境创建、依赖安装、版本锁定整合到一个命令里，真正做到开箱即用。 简单来说，UV 让你从“等 pip 装包”的焦虑中彻底解放出来，让 Python 环境管理变得像呼吸一样自然。

接下来，我们就手把手带你上手 UV，看看它到底有多香。

1 下载安装

github地址：https://github.com/astral-sh/uv

• 在Release页面下载对应的版本，安装即可。

• 设置环境变量

2 配置文件位置

2.1 修改默认位置

2.1.1 迁移 UV 缓存目录

• UV 的缓存默认存放在 C 盘，长期使用可能占用大量空间。建议将其迁移到其他磁盘。

• 查看当前缓存路径

uv cache dir# 输出示例：C:\Users\Administrator\AppData\Local\uv\cache // 默认在C:\Users\<用户名>\AppData\Local\uv\cache

• 设置自定义缓存路径,在系统环境变量中添加 UV_CACHE_DIR，值为目标路径（如 D:\uv\cache）。新开终端窗口后立即生效。

2.1.2 迁移 UV Python 安装目录

• 查看当前 Python 安装路径

uv python dir# 输出示例：C:\Users\Administrator\AppData\Roaming\uv\python // 默认在C:\Users\<用户名>\AppData\Roaming\uv\python

• 在系统环境变量中添加 UV_PYTHON_INSTALL_DIR ，值为目标路径（如 D:\uv\python）。新开终端窗口后立即生效。

2.1.3 如图所示

3 安装python环境

UV 不仅是一个包管理器，还内置了 Python 解释器的下载与管理功能。这意味着你无需手动前往官网下载安装包，也不需要处理复杂的多版本共存问题。通过几条简单的命令，UV 就能帮你完成 Python 版本的安装、切换和卸载，整个过程干净利落。

以下是常用的 Python 版本管理命令：

• uv python install <version>
  ： 安装 Python 版本。例如：uv python install 3.11.5。
• uv python uninstall <version>
  ： 卸载 Python 版本。例如：uv python uninstall 3.11.5。
• uv python list
  ： 查看可用的Python版本。
• uv python pin
  ：将当前项目（目录）钉使用特定的Python版本。例如：uv python pin 3.11.5。
• uv python find
  ： 查找当前项目（目录）下.python-version文件下的版本。
• uv python default 3.11.5
  ：·设置当前项目使用的Python版本。例如：uv python default 3.11.5。

提示：pin 和 default 的区别在于——pin 作用于单个项目，适用于团队协作时统一开发环境；default 作用于整个系统，适合个人日常开发时设定首选版本。

4 项目使用

UV 采用现代化的项目管理工作流，以 pyproject.toml 为核心配置文件，将依赖管理、环境同步、构建发布等环节串联在一起。相比传统的 requirements.txt + venv 组合，这种方式更加规范、可维护，也更符合 Python 社区的最新标准。

以下是 UV 项目管理的常用命令：

• uv init： 创建一个新的 Python 项目。例如：uv init -p 3.11.5 my_project。

• uv add：在项目中添加依赖。例如：uv add requests。

• uv remove：从项目中移除依赖。例如：uv remove requests。

• uv sync：将项目的依赖关系与环境同步。例如：uv sync。

• uv run：在项目环境中运行命令。例如：uv run python main.py。

• uv tree：查看该项目的依赖树。例如：uv tree。

• uv lock：为项目的依赖创建锁文件。例如：uv lock。

• uv build：将项目建立到分发档案中。例如：uv build。

• uv publish：将项目发布到包索引中。例如：uv publish。

提示：uv sync 会自动创建和管理虚拟环境，你无需手动执行 venv 或 source activate。uv lock 生成的锁文件建议提交到版本控制，确保团队成员和生产环境使用完全一致的依赖版本。

5 其他实用命令

除了项目管理和包安装的核心功能外，UV 还提供了一系列实用命令，用于日常的维护、诊断和自身升级。掌握这些命令可以帮助你更好地掌控 UV 的运行状态，及时清理冗余数据，保持工具本身处于最新版本。

以下是 UV 的常用维护与管理命令：

• uv cache clean
  ： 删除缓存条目。例如：uv cache clean。
• uv cache prune
  ：删除过时的缓存条目。例如：uv cache prune。
• uv cache dir
  ： 显示 UV 缓存目录路径。例如：uv cache dir。
• uv tool dir
  ： 显示 UV 工具目录路径。例如：uv tool dir。
• uv python dir
  ： 显示 UV 安装的 Python 版本路径。例如：uv python dir。
• uv self update
  ： 将UV更新到最新版本。例如：uv self update。

提示：uv cache clean 和 uv cache prune 的区别在于——前者是全量清理，适合空间告急时使用；后者是增量清理，只移除不再需要的缓存，推荐作为定期维护操作。uv self update 让你无需手动下载安装包，一条命令即可完成 UV 自身的版本升级。

6. pip 相关

对于已经习惯 pip 工作流的开发者，UV 提供了几乎完全兼容的命令行接口。你可以直接将 pip 替换为 uv pip，无需改变原有的操作习惯，却能享受到 UV 带来的数十倍速度提升。无论是迁移现有项目，还是在 CI/CD 环境中加速构建，这套兼容命令都能让你无缝过渡。

以下是 UV 提供的 pip 兼容命令：

• uv pip install -r requirements.txt
  : 安装requirements.txt中的包。
• uv pip install
  ：将包安装到当前环境中。例如：uv pip install requests。
• uv pip show
  ： 显示已安装包的详细信息。例如：uv pip show requests。
• uv pip freeze
  ： 列出已安装的软件包及其版本。例如：uv pip freeze。
• uv pip check
  ：检查当前环境是否兼容的包。例如：uv pip check。
• uv pip list
  ： 列出已安装的软件包。例如：uv pip list。
• uv pip uninstall
  ： 卸载包。例如：uv pip uninstall requests。
• uv pip tree
  ：查看环境的依赖树。例如：uv pip tree。

提示：uv pip 系列命令在设计上尽量保持与原生 pip 的行为一致，因此你可以将现有脚本中的 pip 直接替换为 uv pip 来获得性能提升。不过需要注意，uv pip 并非 pip 的完全克隆，某些边缘特性可能存在差异，建议在切换后进行充分测试。