Python uv 简明教程
<h2 id="告别依赖地狱用-uv-重塑你的-python-开发体验">告别依赖地狱：用 uv 重塑你的 Python 开发体验</h2><p>如果你长期使用 Python，一定对下面这些场景不陌生：</p>
<ol>
<li>创建一个新项目，<code>pip install</code> 了几个包，忽然发现版本冲突，陷入无尽的 <code>pip install</code> 和 <code>pip uninstall</code> 循环。</li>
<li>项目依赖文件 <code>requirements.txt</code> 越来越大，分不清哪些是核心依赖，哪些是依赖的依赖。</li>
<li>想尝试新工具 <code>poetry</code> 或 <code>pdm</code>，但觉得学习曲线陡峭，又回到了老路。</li>
<li>团队协作时，别人的环境能跑，你的就是报错，最后发现是某个底层库的版本差了一个小数点。</li>
</ol>
<p>这些问题，归根结底是 Python 的包管理和项目依赖管理长期处于一种“自由散漫”的状态。<code>pip</code> 很好，但它只是个安装器；<code>venv</code> 能隔离环境，但用起来稍显繁琐；而 <code>poetry</code>、<code>pdm</code> 等现代工具又带来了新的概念。</p>
<p>今天，我要介绍一个全新的工具：<strong><code>uv</code></strong>。它由 Astral 公司（打造了 Ruff 这个极速的 Python linter）开发，旨在用一个二进制文件，解决从包安装到项目管理的绝大部分问题。它的核心特点是：<strong>极致的快</strong>和<strong>极致的简单</strong>。</p>
<h3 id="一uv-是什么">一、uv 是什么？</h3>
<p>你可以把 <code>uv</code> 理解为 Python 工具链的“瑞士军刀”或“超级充电器”。它在一个单一的、用 Rust 编写的二进制文件中，提供了以下功能：</p>
<ul>
<li><strong>一个超快的、兼容 <code>pip</code> 和 <code>pip-tools</code> 的包安装器</strong>。</li>
<li><strong>一个项目虚拟环境管理器和创建器</strong>。</li>
<li><strong>一个项目依赖锁文件生成器</strong>（类似 <code>poetry.lock</code>）。</li>
<li><strong>一个快速的 <code>pyproject.toml</code> 项目脚手架生成器</strong>。</li>
</ul>
<p>它的目标是成为 Python 开发者的默认工具，一个命令替代一堆命令。</p>
<h3 id="二极速安装">二、极速安装</h3>
<p>打开你的终端（macOS/Linux），一行命令即可安装：</p>
<pre><code class="language-bash">curl -LsSf https://astral.sh/uv/install.sh | sh
</code></pre>
<p>对于 Windows 用户（PowerShell）：</p>
<pre><code class="language-powershell">powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
</code></pre>
<p>安装完成后，重新启动终端，输入 <code>uv --version</code> 查看是否成功。你会立刻感受到它的第一个优点：<strong>作为一个二进制文件，它启动和运行都异常迅速</strong>。</p>
<h3 id="三从零开始一个项目感受魔法">三、从零开始一个项目：感受魔法</h3>
<p>让我们从头创建一个名为 <code>my-awesome-app</code> 的项目，你会看到 <code>uv</code> 如何简化工作流。</p>
<h4 id="1-创建项目目录并进入">1. 创建项目目录并进入</h4>
<pre><code class="language-bash">mkdir my-awesome-app && cd my-awesome-app
</code></pre>
<h4 id="2-使用-uv-init-快速搭建项目脚手架">2. 使用 <code>uv init</code> 快速搭建项目脚手架</h4>
<p>这是 <code>uv</code> 独有的便捷功能。</p>
<pre><code class="language-bash">uv init
</code></pre>
<p>它会交互式地询问你项目名称、版本等，并一键生成标准的、现代的 <code>pyproject.toml</code> 文件，以及一个 <code>README.md</code>。这比手动编写 <code>pyproject.toml</code> 要友好得多。</p>
<h4 id="3-添加依赖快到难以置信">3. 添加依赖：快到难以置信</h4>
<p>假设我们的项目需要 <code>requests</code> 和 <code>flask</code>。使用 <code>uv add</code> 命令，它类似于 <code>poetry add</code>。</p>
<pre><code class="language-bash">uv add requests flask
</code></pre>
<p><strong>感受一下速度</strong>。你会发现安装过程几乎是瞬间完成的。<code>uv</code> 不仅从网络下载快，其内部的依赖解析算法也极其高效。</p>
<p>此时，查看你的 <code>pyproject.toml</code>，依赖已经被自动添加：</p>
<pre><code class="language-toml">
name = "my-awesome-app"
version = "0.1.0"
dependencies = [
"requests",
"flask",
]
</code></pre>
<p>同时，它会生成一个 <code>uv.lock</code> 文件，精确锁定了所有依赖（包括次级依赖）的版本，确保项目在任何地方都能完全复现。</p>
<h4 id="4-进入虚拟环境并运行-python">4. 进入虚拟环境并运行 Python</h4>
<p><code>uv</code> 自动管理着虚拟环境。你可以用 <code>uv venv</code> 显式创建一个，但更简单的方式是直接使用 <code>uv run</code>。</p>
<pre><code class="language-bash"># 直接运行一个命令，uv 会确保它在正确的虚拟环境中执行
uv run python -c "import requests; print(requests.__version__)"
# 或者启动一个在虚拟环境中的 Python 解释器 shell
uv python
</code></pre>
<p>你不需要手动 <code>source venv/bin/activate</code>，<code>uv run</code> 和 <code>uv python</code> 帮你处理了一切，减少了上下文切换。</p>
<h3 id="四在已有项目中使用-uv">四、在已有项目中使用 uv</h3>
<p>如果你已经有一个使用 <code>requirements.txt</code> 或 <code>pyproject.toml</code> 的项目，<code>uv</code> 可以无缝接入。</p>
<h4 id="场景-a只有-requirementstxt">场景 A：只有 <code>requirements.txt</code></h4>
<pre><code class="language-bash"># 安装所有依赖（速度比 pip install -r requirements.txt 快一个数量级）
uv pip install -r requirements.txt
# 或者，如果你想升级到现代工作流，可以生成 lock 文件
uv lock --requirements-in requirements.txt --locked
</code></pre>
<h4 id="场景-b已有-pyprojecttoml比如-poetry-项目">场景 B：已有 <code>pyproject.toml</code>（比如 Poetry 项目）</h4>
<p><code>uv</code> 完全支持 <code>pyproject.toml</code> 作为依赖源。</p>
<pre><code class="language-bash"># 安装 pyproject.toml 中声明的所有依赖
uv sync
</code></pre>
<p><code>uv sync</code> 是核心命令，它会读取 <code>pyproject.toml</code>，根据 <code>uv.lock</code> 安装精确版本。如果没有 <code>uv.lock</code>，它会解析并创建一个。</p>
<h3 id="五核心命令速查">五、核心命令速查</h3>
<table>
<thead>
<tr>
<th style="text-align: left">命令</th>
<th style="text-align: left">作用</th>
<th style="text-align: left">传统等效命令</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left"><code>uv add <package></code></td>
<td style="text-align: left">添加依赖并更新 <code>pyproject.toml</code></td>
<td style="text-align: left"><code>poetry add <package></code></td>
</tr>
<tr>
<td style="text-align: left"><code>uv sync</code></td>
<td style="text-align: left">同步依赖（安装/更新）</td>
<td style="text-align: left"><code>poetry install</code> / <code>pip install -e .</code></td>
</tr>
<tr>
<td style="text-align: left"><code>uv run <command></code></td>
<td style="text-align: left">在项目虚拟环境中运行命令</td>
<td style="text-align: left"><code>source venv/bin/activate && <command></code></td>
</tr>
<tr>
<td style="text-align: left"><code>uv python</code></td>
<td style="text-align: left">启动项目虚拟环境的 Python 解释器</td>
<td style="text-align: left"><code>source venv/bin/activate && python</code></td>
</tr>
<tr>
<td style="text-align: left"><code>uv lock</code></td>
<td style="text-align: left">生成/更新 <code>uv.lock</code> 锁文件</td>
<td style="text-align: left"><code>poetry lock</code></td>
</tr>
<tr>
<td style="text-align: left"><code>uv init</code></td>
<td style="text-align: left">交互式创建 <code>pyproject.toml</code></td>
<td style="text-align: left">手动创建</td>
</tr>
<tr>
<td style="text-align: left"><code>uv pip compile</code></td>
<td style="text-align: left">编译 <code>requirements.txt</code>（高级）</td>
<td style="text-align: left"><code>pip-compile</code></td>
</tr>
</tbody>
</table>
<h3 id="六为什么选择-uv一个简单的总结">六、为什么选择 uv？一个简单的总结</h3>
<ol>
<li><strong>速度就是王道</strong>：用 Rust 重写的依赖解析和下载逻辑，让安装包的过程从“喝杯咖啡”变成“眨下眼睛”。</li>
<li><strong>统一体验</strong>：一个 <code>uv</code> 命令涵盖了从创建、依赖管理到环境运行的全流程，无需在 <code>pip</code>、<code>venv</code>、<code>virtualenvwrapper</code>、<code>poetry</code> 之间来回切换。</li>
<li><strong>兼容并蓄</strong>：它尊重现有的 Python 生态。既支持传统的 <code>requirements.txt</code>，也拥抱现代的 <code>pyproject.toml</code>。你可以逐步迁移，没有负担。</li>
<li><strong>设计简洁</strong>：没有过多抽象概念。如果你会用 <code>pip</code>，就能毫无障碍地上手 <code>uv</code> 的大部分功能。</li>
</ol>
<h3 id="七进阶提示">七、进阶提示</h3>
<ul>
<li><strong>与 IDE 配合</strong>：在 PyCharm 或 VSCode 中，只需将解释器路径指向 <code>uv</code> 创建的虚拟环境（通常位于 <code>项目目录/.venv</code> 下）即可。</li>
<li><strong>用于 CI/CD</strong>：<code>uv</code> 的极速安装特性在 GitHub Actions 等 CI 环境中能显著缩短构建时间。</li>
<li><strong>离线模式</strong>：<code>uv</code> 对缓存有良好的支持，适合离线或内网环境。</li>
</ul>
<h3 id="结语">结语</h3>
<p>Python 的世界正在向现代化演进，<code>pyproject.toml</code> 正在成为标准。<code>uv</code> 在这个时间点出现，像一位带着最优解的技术伙伴。它没有试图颠覆什么，而是用惊人的工程效率和简洁的设计，把那些繁琐、缓慢的事情一次性做好了。</p>
<p>如果你是 Python 新手，我建议你从 <code>uv</code> 开始，它能让你避开很多“历史坑”。如果你是老手，不妨试试 <code>uv</code>，那种流畅的速度感，很可能让你再也回不去。</p>
<p>正如软件开发中的一句老话：“最好的工具，是那个让你感觉不到存在的工具。” <code>uv</code> 正在朝着这个方向大步迈进。</p>
<blockquote>
<p>技术不是用来炫耀的，而是用来解决问题的。<code>uv</code> 解决的就是“等待”和“混乱”这两个最普通又最恼人的问题。—— 模仿阮一峰/廖雪峰的语气</p>
</blockquote>
<p>（本篇教程基于 <code>uv</code> 0.4.x 版本，其发展迅速，请关注官方文档以获取最新特性。）</p>
<p><strong>参考链接：</strong></p>
<ul>
<li>uv 官方网站</li>
<li>uv GitHub 仓库</li>
</ul><br><br>
来源：https://www.cnblogs.com/thxiso/p/19412801
頁:
[1]