‍♂️ 个人主页小李同学_LSH的主页✍ 作者简介LLM学习者 希望大家多多支持我们一起进步如果文章对你有帮助的话欢迎评论 点赞 收藏 加关注目录一、uv 到底是什么为什么这两年越来越多人开始用它亮点二、先安装 uv一步到位就够了三、官方最推荐的用法项目工作流1. 创建一个新项目2. 这个项目目录里的文件分别干什么四、最顺手的一套命令uv add、uv run、uv sync1. 添加依赖2. 运行项目3. 手动同步环境五、更容易接受的路线uv venv uv pip1. 创建虚拟环境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 syncuv add -r requirements.txt -c constraints.txt1. 添加依赖项目工作流里最常用的命令就是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.txt2. 运行项目uv run是 uv 项目工作流里最舒服的部分。官方说明写得非常明确每次执行uv run之前uv 都会先检查 lockfile 是否和pyproject.toml一致再检查当前环境是否和 lockfile 一致。也就是说它会自动帮你做一层“锁定与同步校验”然后确保命令在正确依赖版本的环境里执行。uv run main.py uv run python app.py uv run -- flask run -p 30003. 手动同步环境有时候你还是会想显式同步一下环境尤其是团队协作、切分支、刚拉代码时。这时直接用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 venvuv 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.112. 安装依赖创建完环境后可以直接使用uv pip install官方说明这套命令会直接面向虚拟环境工作这一点和项目模式下“自动管理环境”不同。uv pip install requests flask uv pip install ruff3. 编译与同步依赖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 venvuv 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 环境管理方式。