【uv】【AI】环境使用指南：从虚拟环境创建到依赖管理，一篇讲清 Python 新一代工作流(深度学习必备)

🤵‍♂️ 个人主页：小李同学_LSH的主页

✍🏻 作者简介：LLM学习者 🐋 希望大家多多支持，我们一起进步！😄 如果文章对你有帮助的话， 欢迎评论 💬点赞👍🏻 收藏 📂加关注+

目录

一、uv 到底是什么，为什么这两年越来越多人开始用它

亮点

二、先安装 uv：一步到位就够了

三、官方最推荐的用法：项目工作流

1. 创建一个新项目

2. 这个项目目录里的文件分别干什么

四、最顺手的一套命令：uv add、uv run、uv sync

1. 添加依赖

2. 运行项目

3. 手动同步环境

五、更容易接受的路线：uv venv + uv pip

1. 创建虚拟环境

2. 安装依赖

3. 编译与同步依赖

六、一个很容易忽略的细节：很多时候不需要手动 activate

七、uv 和 pip、venv、poetry 到底是什么关系

在 Python 开发里，很多人都经历过这样一套流程：先用

python -m venv

创建环境，再用

pip install

装包，项目变复杂以后再补

requirements.txt、pip-tools、poetry、pyenv。

工具越来越多，职责越来越散，最后最常见的问题反而不是“不会装包”，而是“环境能不能复现”“团队机器上能不能跑起来”“依赖到底该以哪个文件为准”。uv 想解决的，正是这类分散的工作流问题。官方把它定位成一套统一工具，覆盖项目管理、锁文件、Python 版本管理、工具安装，以及一套兼容 pip 的命令接口。

这篇文章不只讲“怎么安装 uv”，更重点讲两条最常用的路线：一条是 uv 官方更推荐的项目工作流，另一条是更贴近传统习惯的

uv venv + uv pip

工作流。看完之后，基本可以把“建环境、装依赖、锁版本、跑项目”这一整套事情理顺。

一、uv 到底是什么，为什么这两年越来越多人开始用它

uv 官方首页给出的定位很直接：它希望用一套工具替代

https://uv.oaix.tech/https://uv.oaix.tech/

亮点

• 🚀 一个工具即可取代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等。
• ⚡️ 比 pip 快 10-100 倍。
• 🗂️ 提供全面的项目管理，并带有通用锁文件。
• ❇️ 运行脚本，支持内联依赖元数据。
• 🐍 安装和管理 Python 版本。
• 🛠️ 运行和安装 作为 Python 包发布的工具。
• 🔩 包含一个 pip 兼容接口，以熟悉的 CLI 提供性能提升。
• 🏢 支持 Cargo 风格的工作区，适用于可扩展项目。
• 💾 磁盘空间高效，具有用于依赖项去重的全局缓存。
• ⏬ 无需 Rust 或 Python，即可通过 curl 或 pip 安装。
• 🖥️ 支持 macOS、Linux 和 Windows。

pip、pip-tools、pipx、poetry、pyenv、virtualenv

等常见工具组合；同时它还提供项目管理、通用锁文件、Python 版本安装与管理、脚本运行、工具安装，以及一套 pip-compatible 接口。对大多数开发者来说，这里面最有价值的不是“命令更酷”，而是工作流更统一。

换句话说，uv 的思路不是只替代

pip install

这一条命令，而是把下面几件事放回一套工具里：

• 创建项目
• 创建虚拟环境
• 管理依赖
• 锁定依赖版本
• 运行项目命令
• 管理 Python 版本

这也是为什么 uv 比单独的 venv 或 pip 更适合写成“环境使用指南”，因为它讨论的已经不只是一个环境目录，而是一整套项目环境管理方式。

二、先安装 uv：一步到位就够了

官方推荐的安装方式是使用独立安装脚本。macOS / Linux 可以这样安装，Windows PowerShell 则使用另一条命令。安装完成后，先用

uv –version

检查是否生效。安装脚本之外，官方也提到 uv 支持通过 pip、Homebrew 等方式安装，但从入门角度看，独立安装器最省事。

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 检查版本
uv –version

我用的window11，就用

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

$env:Path = "C:\\Users\\Administrator\\.local\\bin;$env:Path"

三、官方最推荐的用法：项目工作流

uv 文档里把“Working on projects”单独作为一大块来写，核心思路就是：让项目围绕 pyproject.toml、.venv 和 uv.lock 运转起来。如果你是准备新开一个 Python 项目，这条路线通常最顺。

1. 创建一个新项目

uv 提供

uv init

来初始化项目。官方说明里写得很清楚：可以直接

uv init hello-world

在目标目录创建项目，也可以进入一个已有目录后执行

uv init

默认创建的是 application 项目，想创建 library 则可以加 –lib。

uv init hello-uv
cd hello-uv

初始化后，常见会得到这些文件：

.gitignore
.python-version
README.md
main.py
pyproject.toml

官方项目指南明确列出了这批初始文件；之后第一次运行项目命令时，uv 还会继续创建 .venv 和 uv.lock。

2. 这个项目目录里的文件分别干什么

这是 uv 最值得讲清的一部分。很多教程只给命令，不解释文件，读者用几次以后还是容易乱。

pyproject.toml 是项目元数据和依赖的中心文件。你可以手动编辑它，也可以通过

uv add、uv remove

这样的命令来改。.python-version 记录项目默认使用的 Python 版本，uv 创建项目虚拟环境时会参考它。.venv 是项目自己的虚拟环境目录。uv.lock 则保存精确解析后的依赖版本，官方明确建议把它提交到版本控制，以便跨机器保持可复现安装。

这一点要重点记住：

pyproject.toml 说的是“我大概要什么依赖”，uv.lock 说的是“最终解析出来的精确版本是什么”。

四、最顺手的一套命令：uv add、uv run、uv sync

uv add -r requirements.txt -c constraints.txt

1. 添加依赖

项目工作流里最常用的命令就是

uv add

官方文档说明，uv add 会把依赖写进 pyproject.toml，同时更新锁文件和项目环境。也就是说，你不是“先改文件，再手动装包”，而是一条命令把三件事做完。

uv add requests
uv add flask

开发依赖也可以单独加：

uv add –dev pytest

老项目如果已经有 requirements.txt，官方也给了迁移方式，可以直接通过 -r 把依赖导入进来。

uv add -r requirements.txt -c constraints.txt

2. 运行项目

uv run

是 uv 项目工作流里最舒服的部分。官方说明写得非常明确：每次执行 uv run 之前，uv 都会先检查 lockfile 是否和 pyproject.toml 一致，再检查当前环境是否和 lockfile 一致。也就是说，它会自动帮你做一层“锁定与同步校验”，然后确保命令在正确依赖版本的环境里执行。

uv run main.py
uv run python app.py
uv run — flask run -p 3000

3. 手动同步环境

有时候你还是会想显式同步一下环境，尤其是团队协作、切分支、刚拉代码时。这时直接用 uv sync。项目指南里说明，.venv 和 uv.lock 会在运行 uv run、uv sync 或 uv lock 这类项目命令时生成或更新。

uv sync

同步完成后，也可以像传统方式那样激活虚拟环境再执行命令。官方项目文档特别提醒：不使用 uv run 的情况下，要先激活虚拟环境再运行脚本和命令。

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\\Scripts\\activate

五、更容易接受的路线：uv venv + uv pip

上面那套更适合新项目。但很多人手上已经有老项目，或者就是习惯“先建环境，再装包”。这时 uv 并没有逼你彻底改习惯，它专门提供了 uv pip 接口。官方把这部分叫做 pip interface，并明确说：这是一套给 power users 和还没准备从 pip / pip-tools 工作流迁移出去的项目用的接口。

1. 创建虚拟环境

官方环境文档说明，uv 默认要求使用虚拟环境；创建默认环境的命令非常简单，就是 uv venv，默认目录是 .venv。还可以指定名称或路径，也可以显式指定 Python 版本。并且如果本地没有对应版本，uv 可以为你下载 Python。

uv venv
uv venv myenv
uv venv –python 3.11

2. 安装依赖

创建完环境后，可以直接使用

uv pip install

官方说明这套命令会直接面向虚拟环境工作，这一点和项目模式下“自动管理环境”不同。

uv pip install requests flask
uv pip install ruff

3. 编译与同步依赖

uv pip 还覆盖了很多 pip-tools 常见场景，比如生成锁定后的 requirements 文件，以及按 requirements 文件同步环境。对于老项目迁移来说，这部分非常实用。

uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

六、一个很容易忽略的细节：很多时候不需要手动 activate

这是 uv 和传统 venv 使用习惯差异比较大的地方。官方环境文档提到，当虚拟环境使用默认名称 .venv 时，uv 后续调用会自动发现并使用它。也就是说，像

uv pip install、uv run

这类命令，经常并不要求你先执行 source .venv/bin/activate。

当然，你仍然可以激活环境。激活的意义主要在于：接下来想直接用 python、pytest、flask 这类命令，而不是每次都通过 uv run 或 uv pip 进入环境。项目文档也明确说了，不通过 uv run 执行项目命令时，需要先激活虚拟环境。

这个区别可以总结成一句话：

uv 更鼓励“命令带环境走”，而不是“先切环境再做事”。

七、uv 和 pip、venv、poetry 到底是什么关系

官方首页说它想替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等常见工具。这个表述更适合理解成“覆盖这些工具常见使用场景”，而不是“它在每个细节上都一模一样”。

更准确一点的理解是：

• uv venv 可以替代 python -m venv
• uv pip install / compile / sync 可以覆盖很多 pip + pip-tools 场景
• uv init / add / run / sync 更像一整套项目依赖管理工作流
• uv 还可以安装和管理 Python 版本，这部分又覆盖了 pyenv 一部分常见需求

但这里一定要加一句提醒：官方的 pip compatibility 页面明确写了，uv 不是 pip 的精确克隆。越偏离常见 pip 工作流，越可能遇到行为差异；这些差异有些是设计使然，有些可能是实现细节，有些也可能是 bug。

所以最稳的用法不是“把所有老习惯原样搬过来”，而是：

新项目尽量用 uv 的项目工作流，老项目再用 uv pip 渐进迁移。

uv 之所以值得单独写一篇环境使用指南，不是因为它只是“更快的 pip”，而是因为它把 Python 环境管理这件事，从“若干工具拼装”重新拉回到“一套更统一的工作流”上。官方给出的定位也很明确：既能管理项目、锁文件和 Python 版本，也保留了熟悉的 pip-compatible 接口。

对于大多数开发者来说，最有价值的不是记住多少命令，而是先建立一个判断标准：

• 新项目，优先用项目工作流
• 老项目，优先用 uv pip 低风险迁移
• 把 pyproject.toml 和 uv.lock 当成项目环境的核心文件
• 把“先 activate 再做事”的习惯，慢慢改成“用 uv 直接驱动环境”

这样用一段时间之后，你会发现 uv 真正替代掉的不是某一条命令，而是过去那种零碎、容易漂移、难以复现的 Python 环境管理方式。