原人 發表於 2025-4-22 10:21:00

Python UV 使用手册

<h1 id="python-uv-使用手册">Python UV 使用手册</h1>
<p>网页收藏夹使用</p>
<h2 id="一常用命令">一、常用命令</h2>
<pre><code class="language-shell"># 项目初始化 [默认当前文件夹]
uv init
</code></pre>
<pre><code class="language-shell"># 创建虚拟环境
uv venv
</code></pre>
<pre><code class="language-shell"># 指定 Python 版本
uv venv --python 3.11
</code></pre>
<pre><code class="language-shell"># 激活环境
.venv\Scripts\activate
</code></pre>
<pre><code class="language-shell"># 运行脚本
uv run script.py
</code></pre>
<pre><code class="language-shell"># 添加依赖（会更新 pyproject.toml）
uv add flask [--dev]
</code></pre>
<pre><code class="language-shell"># 安装依赖（不更新配置文件）
uv pip install flask
</code></pre>
<pre><code class="language-shell"># 同步项目依赖
uv sync
</code></pre>
<pre><code class="language-shell"># 更新依赖
uv sync --upgrade
</code></pre>
<pre><code class="language-shell"># 更新特定包
uv sync --upgrade-package flask
</code></pre>
<h2 id="二更换国内源挑一个">二、更换国内源（挑一个）</h2>
<h3 id="1-项目配置">1 项目配置</h3>
<h4 id="pyprojecttoml-添加">pyproject.toml 添加</h4>
<pre><code>[]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
</code></pre>
<h4 id="uvtoml-添加">uv.toml 添加</h4>
<pre><code>[]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
</code></pre>
<h3 id="2-环境变量">2 环境变量</h3>
<h4 id="终端临时用">终端临时用</h4>
<pre><code class="language-shell">uv add --default-index https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple fastmcp
</code></pre>
<h4 id="系统永久">系统永久</h4>
<pre><code class="language-shell">vi ~/.bashrc
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 额外镜像地址
export EXTRA_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
</code></pre>
<h2 id="三安装-uv">三、安装 UV</h2>
<h4 id="1-macos-和-linux">1 macOS 和 Linux</h4>
<pre><code class="language-shell">curl -LsSf https://astral.sh/uv/install.sh | sh
</code></pre>
<h4 id="2-windows">2 Windows</h4>
<p>在 PowerShell 中执行以下命令：</p>
<pre><code class="language-powershell">powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
</code></pre>
<p>验证安装</p>
<pre><code class="language-shell">uv --version
</code></pre>
<h2 id="四依赖管理">四、依赖管理</h2>
<h3 id="1-安装依赖">1 安装依赖</h3>
<pre><code class="language-shell">uv add fastmcp
uv pip install fastmcp
</code></pre>
<h6 id="开发环境用--dev">开发环境用：--dev</h6>
<h6 id="指定生成环境--production">指定生成环境：--production</h6>
<pre><code class="language-shell">uv add "numpy; python_version &gt;= '3.11'; sys_platform == 'linux'"
</code></pre>
<h3 id="2-删除依赖">2 删除依赖</h3>
<pre><code class="language-shell">uv remove fastmcp
uv pip uninstall fastmcp
</code></pre>
<h3 id="3-查看依赖">3 查看依赖</h3>
<pre><code class="language-shell">uv pip list
</code></pre>
<h3 id="4-导出依赖">4 导出依赖</h3>
<pre><code class="language-shell">uv pip freeze &gt; requirements.txt
uv pip compile pyproject.toml -o requirements.txt
</code></pre>
<h3 id="5-批量安装">5 批量安装</h3>
<pre><code class="language-shell">uv pip install -r requirements.txt
uv add -r requirements.txt
uv pip install -r pyproject.toml
</code></pre>
<h3 id="6-清除缓存">6 清除缓存</h3>
<pre><code class="language-shell">uv cache clean
uv pip cache purge
</code></pre>
<h3 id="7-项目依赖树">7 项目依赖树</h3>
<pre><code class="language-shell">uv tree
</code></pre>
<hr>
<h3 id="8-改习惯">8 改习惯</h3>
<p>将以前的 <code>pip xxx</code> 替换为 <code>uv pip xxx</code></p>
<pre><code class="language-shell"># 批量安装并生成锁定文件（类似 pip-tools）
uv pip compile ./requirements.in --universal --output-file ./requirements.txt
</code></pre>
<p>全局系统级别使用，添加 <code>--system</code> 参数:</p>
<pre><code class="language-shell">uv pip install --system pandas
</code></pre>
<h2 id="五项目管理与锁定文件">五、项目管理与锁定文件</h2>
<h3 id="1-初始化项目管理依赖">1 初始化项目，管理依赖</h3>
<pre><code class="language-shell">uv init hello-world# 初始化项目
cd hello-world

uv add 'requests==2.31.0' # 增加依赖
uv lock --upgrade-package requests # 更新项目依赖
uv remove requests # 删除项目依赖
</code></pre>
<h3 id="2-项目结构">2 项目结构</h3>
<pre><code class="language-shell">.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock
</code></pre>
<h3 id="3-运行项目脚本">3 运行项目脚本</h3>
<pre><code class="language-shell">运行项目脚本
</code></pre>
<h3 id="4-更新配置项目环境">4 更新配置项目环境</h3>
<pre><code class="language-shell">git clone git/yb-mrp.git &amp;&amp; cd yb-mrp
uv sync # 已存在项目安装项目依赖（自动解析锁定文件）
</code></pre>
<h3 id="5-显示项目的依赖项树">5 显示项目的依赖项树</h3>
<pre><code class="language-shell">uv tree --outdated # 以树形查看更新包
uv tree --depth 2# 查看2级的依赖，防止依赖树过大
</code></pre>
<h2 id="六管理全局-cli-工具替代-pipx">六、管理全局 CLI 工具：替代 pipx</h2>
<pre><code class="language-shell"># 全局安装 black 代码格式化工具（类似 pipx）
$ uv tool install black
$ uv tool run black ./myfile.py # 运行全局工具

# 同时提供更易用的 uvx 命令，类似 JavaScript 生态中的 npx
$ uvx pycowsay 'hello world!'
Installed 1 package in 19ms

------------
&lt; hello world! &gt;
------------
   \   ^__^
    \(oo)\_______
       (__)\       )\/\
         ||----w |
         ||   ||


$ uvx ruff format ./myscript.py
</code></pre>
<h2 id="七python-版本管理替代-pyenv">七、Python 版本管理：替代 pyenv</h2>
<h3 id="1-配置源">1 配置源</h3>
<p>windows</p>
<pre><code class="language-powershell">env:UV_PYTHON_INSTALL_MIRROR="https://gh-proxy.com/github.com/indygreg/python-build-standalone/releases/download"
</code></pre>
<h3 id="2-安装指定-python">2 安装指定 python</h3>
<pre><code class="language-shell">uv python install 3.13.2
</code></pre>
<h3 id="3-查看已安装和可安装的-python-版本">3 查看已安装和可安装的 Python 版本</h3>
<pre><code class="language-shell">uv python list
</code></pre>
<h3 id="4-使用特定版本运行脚本">4 使用特定版本运行脚本</h3>
<pre><code class="language-shell">uvx python@3.13.2 -c "print('hello world')"
</code></pre>
<h3 id="5-镜像">5 镜像</h3>
<pre><code class="language-shell">https://mirror.nju.edu.cn/github-release/indygreg/python-build-standalone/
</code></pre>
<h2 id="八虚拟环境管理-虚拟环境管理">八、虚拟环境管理: 虚拟环境管理</h2>
<h3 id="1-创建并激活">1 创建并激活</h3>
<pre><code class="language-shell">uv venv
source .venv/bin/activate
</code></pre>
<pre><code class="language-shell">uv venv [-p 3.14]
</code></pre>
<h3 id="2-退出">2 退出</h3>
<pre><code class="language-shell">deactivate
uv venv --seed# 强制安装基础包（如pip, setuptools, wheel）
</code></pre>
<h2 id="九工作区支持">九、工作区支持</h2>
<p>工作区通过将大型代码库拆分为具有共同依赖项的多个包来组织大型代码库。在工作区中，每个包定义自己的pyproject.toml ，但工作区共享一个锁定文件，确保工作区以一组一致的依赖项运行。实现 Python 版本的 Monorepo 开发模式。</p>
<p>要创建工作区，请将tool.uv.workspace表添加到pyproject.toml ，这将隐式创建以该包为根的工作区。</p>
<pre><code class="language-shell">
name = "albatross"
version = "0.1.0"
requires-python = "&gt;=3.12"
dependencies = ["bird-feeder", "tqdm&gt;=4,&lt;5"]


bird-feeder = { workspace = true }


members = ["packages/*"]
exclude = ["packages/seeds"]
</code></pre>
<p>工作区目录:</p>
<pre><code class="language-shell">albatross
├── packages
│   ├── bird-feeder
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── bird_feeder
│   │         ├── __init__.py
│   │         └── foo.py
│   └── seeds
│       ├── pyproject.toml
│       └── src
│         └── seeds
│               ├── __init__.py
│               └── bar.py
├── pyproject.toml
├── README.md
├── uv.lock
└── src
    └── albatross
      └── main.py
</code></pre>
<p>它们会公用一个虚拟环境和锁文件。uv 会处理好不同包之间的依赖关系。</p>
<p>运行具体的包命令:</p>
<pre><code class="language-shell">uv run --package bird-feeder
</code></pre>
<h2 id="十全局缓存与去重">十、全局缓存与去重</h2>
<p>uv 使用缓存来避免重新下载（和重新构建）在先前运行中已经访问过的依赖项。</p>
<h3 id="1-看缓存路径">1 看缓存路径</h3>
<pre><code class="language-shell">uv cache dir
# D:\Programs\uv\cache
</code></pre>
<h3 id="2-删除所有缓存">2 删除所有缓存。</h3>
<pre><code class="language-shell">uv cache clean
</code></pre>
<h3 id="3-删除未使用的缓存条目">3 删除未使用的缓存条目</h3>
<pre><code class="language-shell">uv cache purge
</code></pre>
<h3 id="4-配置缓存路径和从全局缓存中使用包的方式">4 配置缓存路径和从全局缓存中使用包的方式：</h3>
<pre><code class="language-powershell">$env:UV_CACHE_DIR=/path/to/code
$env:UV_LINK_MODE=hardlink
</code></pre>
<h2 id="十一迁移">十一、迁移</h2>
<h3 id="pip-迁移到-uv">pip 迁移到 uv</h3>
<pre><code class="language-shell">uv add -r requirements.txt
</code></pre>
<h3 id="conda-迁移到-uv">conda 迁移到 uv</h3>
<p>导出依赖文件 requirements.txt</p>
<pre><code class="language-shell">conda list -e &gt; requirements.txt
</code></pre>
<p>使用想使用 uv pip 管理依赖</p>
<pre><code class="language-shell">uv pip install -r requirements.txt
</code></pre>
<p>如果想使用 uv 项目作为管理</p>
<pre><code class="language-shell">uv add -r requirements.txt
</code></pre>
<h2 id="十一pytorch-场景适配">十一、PyTorch 场景适配</h2>
<p>PyTorch 生态系统是深度学习研究和开发的热门选择。随着 anaconda 许可证变更，对商业许可证的判断更加严格，以及 PyTorch 官方后续不再维护 conda 渠道发行版本，您可以使用 uv 来管理不同 Python 版本和环境中的 PyTorch 项目和 PyTorch 依赖项，甚至可以控制镜像加速index-url的选择（例如，仅 CPU 与 CUDA）。</p>
<p>如下配置，可以看到基于不同的操作系统，我们可以安装不同的 torch 版本，windows 版本安装 cpu 版本的 torch，linux 版本安装 cuda 12.4 版本的 torch。</p>
<pre><code class="language-shell">
name = "project"
version = "0.1.0"
requires-python = "&gt;=3.12.0"
dependencies = [
"torch&gt;=2.6.0",
]


torch = [
{ index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
{ index = "pytorch-cu124", marker = "sys_platform == 'linux'" },
]

[]
name = "pytorch-cpu"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
explicit = true

[]
name = "pytorch-cu124"
url = "https://mirror.sjtu.edu.cn/pytorch-wheels/cu124"
explicit = true
</code></pre>
<h2 id="十二报错汇总">十二、报错汇总</h2>
<h3 id="环境污染">环境污染</h3>
<p>报错： No solution found when resolving dependencies for split (python_full_version == '3.9.*'):<br>
解决：</p>
<pre><code>解决办法：退出其他 python 虚拟环境，只使用 uv 创建的虚拟环境，

检查 pyproject.toml 和 .python-version、uv.lock 中 requires-python 版本，

修改 pyproject.toml 中 python 版本和删除 uv.lock，执行 uv sync
</code></pre>
<h3 id="虚拟环境未激活导致命令失败">虚拟环境未激活导致命令失败</h3>
<p>使用uv run无需手动激活环境，直接执行命令；如果手动激活，需通过 uv sync 确保环境最新。</p>
<h3 id="依赖升级后锁文件未更新">依赖升级后锁文件未更新</h3>
<p>直接修改 pyproject.toml 中的版本约束后，必须运行 <code>uv lock</code> 重新生成锁文件，仅 <code>uv sync</code> 不会更新版本。</p>
<h2 id="十三更新环境依赖">十三、更新环境依赖</h2>
<ol>
<li>直接将 pyproject.toml 这个文件中的某依赖删除</li>
<li>执行 <code>uv lock</code> ：根据 pyproject.toml 更新 uv.lock 文件。</li>
<li>执行 <code>uv sync</code> ：根据 uv.lock 的要求生成实际 python 环境。</li>
<li>执行 <code>uv pip list</code>： 查看当前依赖</li>
</ol>
<p>ps: uv 管理项目的移植后，python 环境安装只需要执行 uv sync 即可将项目中记录的 python 环境建立起来</p>
<h2 id="十四构建与发布">十四、构建与发布</h2>
<h3 id="1-构建发行包">1. 构建发行包</h3>
<p>uv 支持生成标准的 Python 发行包（源包和 wheel 包），只需：</p>
<pre><code class="language-shell">uv build# 在当前目录构建项目
ls dist/# 查看生成的发行包（.tar.gz 和 .whl 文件）
</code></pre>
<p>或</p>
<pre><code class="language-shell">uv build src/my_package# 构建指定目录的包
uv build --package my_lib# 构建工作区中的指定包
</code></pre>
<h3 id="2-发布">2. 发布</h3>
<p>发布前需确保pyproject.toml包含正确的build-system定义。对于私有包，可添加分类器避免误上传：</p>
<p>配置 tom [可选]</p>
<pre><code class="language-tom">
classifiers = ["Private :: Do Not Upload"]# 标记为私有包（PyPI会拒绝）
</code></pre>
<p>发布时支持令牌认证（推荐使用，替代传统用户名密码）：</p>
<pre><code class="language-shell"># 方式1：命令行直接指定令牌
uv publish --token YOUR_PYPI_TOKEN
</code></pre>
<pre><code class="language-shell"># 方式2：通过环境变量安全传递（适合CI/CD）
export UV_PUBLISH_TOKEN=YOUR_PYPI_TOKEN
uv publish
</code></pre>
<h3 id="3-验证包安装避免本地缓存干扰">3. 验证包安装（避免本地缓存干扰）</h3>
<p>构建完成后，可通过隔离环境验证包是否可正常导入：</p>
<pre><code class="language-shell">uv run --with my_package --no-project -- python -c "import my_package"
</code></pre><br><br>
来源：https://www.cnblogs.com/xuehuafeixuan/p/18840162
頁: [1]
查看完整版本: Python UV 使用手册