文章目录

  • 官网：https://uv.doczh.com/

  • 参考文档：https://www.cnblogs.com/haima/p/18928947

常用安装命令对比 vs. pip

命令 pip 说明 uv
安装 package 包 pip install package uv add package
安装 1.0.0 版本的 package 包 pip install package==1.0.0 uv add package==1.0.0
升级 package 包 pip install --upgrade package uv add --upgrade package
pip install -U package 简写 uv add -U package
安装 package 包开发版本 pip install --pre package uv add --pre package
从指定网址安装 package 包 pip install package -i https://... uv add package --index package=https://...
pip install git+https://.../package uv add git+https://.../package
pip install git+https://.../package@v0.27.0 指定标签 uv add git+https://.../package --tag 0.27.0
pip install git+https://.../package@main 指定分支 uv add git+https://.../package --branch main
pip install git+https://.../package#subdirectory=libs/langchain 指定子目录 uv add git+https://.../package#subdirectory=libs/langchain
从 requirements.txt 中安装包 pip install -r requirements.txt uv add -r requirements.txt
在指定平台上安装 package 包 -- uv add "package; sys_platform == 'linux'"
从指定链接安装 package 包 pip install "https://.../xxx.whl" 安装 whl 包 uv add "https://.../xxx.whl"
pip install "https://.../xxx.tar.gz" 安装 tar 包 uv add "https://.../xxx.tar.gz"
pip install "https://.../xxx.zip" 安装 zip 包 uv add "https://.../xxx.zip"
从指定路径安装 package 包 pip install ./example/package-0.1.0-py3-none-any.(whl/tar.gz/zip) uv add /example/package-0.1.0-py3-none-any.(whl/tar.gz/zip)
卸载 package 包 pip uninstall package uv remove package
  • Pip install 命令详解：https://www.cnblogs.com/allenxx/p/18026314

1. 安装 uv

在 Windows 下，通过以下命令安装 uv：

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

这会下载 3 个 exe 文件到路径 C:\Users\Administrator\.local\bin 下：

PS C:\Users\zheliku> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Downloading uv 0.7.13 (x86_64-pc-windows-msvc)
Installing to C:\Users\Administrator\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

To add C:\Users\Administrator\.local\bin to your PATH, either restart your shell or run:

    set Path=C:\Users\Administrator\.local\bin;%Path%   (cmd)
    $env:Path = "C:\Users\Administrator\.local\bin;$env:Path"   (powershell)

可以将这 3 个 exe 放到别的路径下，并设置环境变量，以全局使用 uv。

2. 管理 python

2.1 指定位置

在 powershell 配置文件中修改 python 安装位置：C:\Users\zheliku\Documents\WindowsPowerShell\profile.ps1

添加以下命令指定安装和缓存位置：

$env:UV_PYTHON_INSTALL_DIR = "E:\Python"
$env:UV_CACHE_DIR = "E:\uv\cache"

将上述路径添加到系统 Path 后，可输入以下命令查看安装路径：

uv python dir

2.2 安装 python

使用以下命令查看 python 可/已安装的列表：

uv python list

输入以下命令安装指定版本的 python：

uv python install 3.12

卸载同理：

uv python uninstall 3.12

3. Pycharm 项目配置

3.1 新建环境

使用 pycharm 打开新建项目，为项目添加新的 python 解释器，类型选择 uv，下拉选择已安装的 python 版本。

可以看到新建了 .venv 文件夹和 pyproject.toml 配置文件。

3.2 已有项目

使用 pycharm 打开已有项目，为项目添加已有 python 解释器，类型选择 uv，UV env use 选择当前目录下的 “.venv/Scripts/python.exe”。

3.3 指定 python 版本

输入以下命令切换 python 版本：

# 绑定版本为 3.13.7
uv python pin 3.13.7  # 这会生成 .python-version 文件

# 同步更新
uv sync

最好看看 project.toml 文件中的 requires-python 是否也满足要求，可以手动更改一下。

4. 项目依赖

project.dependencies 表表示上传到 PyPI 或构建 wheel 时使用的依赖项。单个依赖项使用 依赖说明符 语法指定，并且该表遵循 PEP 621 标准。

project.dependencies 定义了项目所需的包列表，以及安装这些包时应使用的版本约束。每个条目都包含一个依赖项名称和版本。条目可能包含特定于平台的包的额外功能或环境标记。例如：

[project]
name = "albatross"
version = "0.1.0"
dependencies = [
  # 此范围内的任何版本
  "tqdm >=4.66.2,<5",
  # 完全是此版本的 torch
  "torch ==2.2.2",
  # 安装带有 torch 额外功能的 transformers
  "transformers[torch] >=4.39.3,<5",
  # 仅在较旧的 Python 版本上安装此包
  # 有关更多信息，请参阅“环境标记”
  "importlib_metadata >=7.1.0,<8; python_version < '3.10'",
  "mollymawk ==0.1.0"
]

5. 安装依赖项

使用 uv 管理项目后，就全部使用 uv 命令，不要使用其他命令混用！

5.1 核心参数

此类参数是 uv add 的基础，用于明确“添加哪些依赖”，分为“直接指定包”和“从文件读取包”两种方式，二者必选其一。

5.1.1 <PACKAGES>...（位置参数）

  • 作用：直接指定要添加的依赖包，需符合 PEP 508 格式（支持版本约束、Git 地址、本地路径等）。常见格式：

    • 包名（自动选最新版）：requests

    • 固定版本：ruff==0.5.0

    • 版本范围：flask>=2.0,<3.0

    • Git 仓库：git+https://github.com/psf/requests.git

    • 本地路径：./my-local-package

  • 使用案例：为项目添加 requests 2.31.0（固定版本）和 flask 2.3.x（次要版本锁定）：

    uv add requests==2.31.0 flask>=2.3.0,<2.4.0

5.1.2 -r, --requirements <REQUIREMENTS>

  • 作用：从指定的“依赖清单文件”（如 requirements.txt）中批量添加依赖，支持标准 pip 风格的 requirements 文件格式。

  • 环境变量：UV_CONSTRAINT（可预先指定约束文件路径）。

  • 使用案例：从项目根目录的 requirements.prod.txt 文件中添加生产环境依赖：

    uv add -r requirements.prod.txt

    若同时指定文件和单个包，会优先合并两者依赖（去重并按版本约束解析）：

    uv add -r requirements.dev.txt pytest-cov==4.1.0

5.2 依赖特性

此类参数用于将依赖归类（如开发依赖、可选依赖）或添加条件约束（如仅特定系统生效），适配项目不同环境的依赖管理需求。

5.2.1 --dev

  • 作用：将依赖添加到“开发依赖组”（对应 pyproject.toml 中的 tool.uv.dev-dependencies），仅用于本地开发（如测试、文档工具），不随项目发布。

  • 环境变量：UV_DEV（设为 1 时默认添加到开发依赖）。

  • 使用案例：添加 pytest（测试工具）和 black（代码格式化工具）到开发依赖：

    uv add --dev pytest==7.4.3 black==24.4.2

5.2.2 --optional <OPTIONAL>

  • 作用：将依赖添加到“可选依赖组”（对应 pyproject.toml 中的 tool.uv.optional-dependencies.<组名>），需用户手动启用（如 uv install "package[组名]"），适用于非核心功能（如文档、扩展功能）。

  • 参数：<OPTIONAL> 为可选依赖组的名称（如 docs、security）。

  • 使用案例：添加 sphinx（文档生成工具）到 docs 可选依赖组，cryptography 到 security 可选依赖组：

    uv add --optional docs sphinx==7.2.6
uv add --optional security cryptography==42.0.5

5.2.3 --group <GROUP>

  • 作用：自定义依赖分组（区别于默认的 dependencies、dev-dependencies），适用于复杂项目的依赖分类（如 utils、api 组）。

  • 使用案例：将 python-dotenv（环境变量管理）和 PyYAML（配置解析）添加到 utils 自定义组：

    uv add --group utils python-dotenv==1.0.1 PyYAML==6.0.1

5.2.4 --editable

  • 作用：以“可编辑模式”添加依赖（类似 pip install -e），适用于本地开发的包（如自己写的工具库）—— 修改源码后无需重新安装，直接生效。

  • 注意：仅支持本地路径依赖（如 ./my-package）或 Git 仓库依赖。

  • 使用案例：以可编辑模式添加本地路径 ./my-utils 下的自定义包：

    uv add --editable ./my-utils

5.2.5 --marker <MARKER>

  • 作用：为依赖添加“环境标记”（PEP 508 标记），仅在满足标记条件的环境中安装（如仅 Windows 系统、特定 Python 版本）。

  • 常见标记：sys_platform == "win32"（Windows）、python_version >= "3.10"（Python ≥3.10）。

  • 使用案例：仅在 Windows 系统中安装 pywin32（Windows 系统交互工具）：

    uv add --marker "sys_platform == 'win32'" pywin32==306

5.2.6 --bounds <BOUNDS>

  • 作用：指定版本约束的“宽松程度”，自动生成对应的版本范围（无需手动写 >=/<）。

  • 可选值：

    • lower：仅锁定最低版本（如 requests>=2.31.0）

    • minor：锁定次要版本（如 requests>=2.31.0,<2.32.0）

    • major：锁定主要版本（如 requests>=2.0.0,<3.0.0）

    • exact：锁定精确版本（如 requests==2.31.0）

  • 使用案例：添加 numpy 并自动生成“次要版本锁定”的约束（即仅更新补丁版本）：

    uv add --bounds minor numpy

5.2.7 --extra <EXTRA>

  • 作用：启用依赖包的“额外功能模块”（如 requests[security] 包含加密相关依赖），等价于在包名后加 [extra]，但更灵活（支持多个 extra）。

  • 使用案例：安装 requests 并启用 security（加密）和 socks（代理）两个额外模块：

    uv add --extra security --extra socks requests

5.2.8 其他依赖控制参数

参数 作用 使用案例
--raw 按“原始格式”添加依赖（不自动处理版本约束或格式），适用于非标准 PEP 508 格式的依赖 uv add --raw "my-package @ file:///D:/wheels/my-package-1.0.0.tar.gz"
--no-sync 仅将依赖添加到 pyproject.toml，不实际同步（安装）到虚拟环境 uv add --no-sync django
--locked 确保添加依赖后 uv.lock 文件不变（若会改变则报错），用于锁定版本的生产环境 uv add --locked requests==2.31.0
--frozen 添加依赖时不重新生成 uv.lock（仅更新 pyproject.toml） uv add --frozen flask

5.3 依赖源

此类参数用于指定依赖的下载源（如国内镜像、私有仓库），解决默认 PyPI 下载慢或访问私有包的问题。

5.3.1 索引

5.3.1.1 --index <INDEX>

  • 作用：添加“额外索引”（补充默认索引），适用于同时从官方 PyPI 和私有仓库下载依赖（如公司内部包）。

  • 环境变量：UV_INDEX

  • 替代 deprecated 选项：--extra-index-url（已废弃，推荐用 --index）。

  • 使用案例：从官方 PyPI 安装 requests，同时从公司私有索引安装 company-utils：

    uv add --index https://private-pypi.example.com/simple/ requests company-utils

    uv 会将索引存储在 [[tool.uv.index]] 中，并添加一个 [tool.uv.sources] 条目：

    [project]
dependencies = ["torch"]

[tool.uv.sources]
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

    定义索引时，可以包含 explicit 标志，以指示该索引 仅 应用于在 tool.uv.sources 中显式指定它的包。如果未设置 explicit，其他包在其他地方找不到时，可能会从该索引解析。

    [[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
5.3.1.2 --default-index <DEFAULT_INDEX>

  • 作用：设置“默认包索引”（替代官方 PyPI https://pypi.org/simple），适用于全局切换镜像（如国内阿里云、腾讯云）。

  • 环境变量：UV_DEFAULT_INDEX

  • 替代 deprecated 选项：-i, --index-url（已废弃，推荐用 --default-index）。

  • 使用案例：从阿里云 PyPI 镜像安装 django：

    uv add --default-index https://mirrors.aliyun.com/pypi/simple/ django==4.2.8
5.3.1.3 -f, --find-links <FIND_LINKS>

  • 作用：从指定的“本地路径”或“URL 目录”查找依赖包（如本地 ./wheels 文件夹中的 .whl 文件），优先于索引下载。

  • 环境变量：UV_FIND_LINKS。

  • 使用案例：从本地 ./wheels 文件夹安装 pandas 的预编译 wheel 文件（避免在线下载）：

    uv add --find-links ./wheels/ pandas==2.1.4
5.3.1.4 --no-index

  • 作用：完全忽略所有索引（包括默认 PyPI 和额外索引），仅从 --find-links 指定的路径或直接 URL 依赖中安装，适用于离线环境。

  • 使用案例：仅从本地 ./offline-wheels 安装 numpy，不访问任何在线索引：

    uv add --no-index --find-links ./offline-wheels/ numpy==1.26.3
5.3.1.5 --index-strategy <INDEX_STRATEGY>

  • 作用：指定多索引的“解析策略”，控制如何从多个索引中选择依赖版本。

  • 可选值：

    • first-index：优先从第一个索引获取（推荐，避免版本混乱）

    • unsafe-first-match：找到第一个匹配版本即使用（可能不稳定）

    • unsafe-best-match：从所有索引中选“最佳版本”（可能跨索引冲突）

  • 环境变量：UV_INDEX_STRATEGY。

  • 使用案例：同时指定公司私有索引和官方 PyPI，优先从私有索引获取依赖：

    uv add --index https://private-pypi.example.com/simple/ --index https://pypi.org/simple/ --index-strategy first-index company-utils requests

5.3.2 Git

要添加一个 Git 依赖源，在兼容 Git 的 URL（即你使用 git clone 时所用的 URL）前加上 git+。

uv add git+https://github.com/encode/httpx

[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx" }

从 Git 仓库添加依赖时，指定使用的“commit 哈希”（--rev）、“标签”（--tag）或“分支”（--branch），避免使用默认主分支。

5.3.2.1 --tag <TAG>

可以指定特定的 Git 引用，例如标签：

uv add git+https://github.com/encode/httpx --tag 0.27.0
5.3.2.2 --branch <BRANCH>

或者，分支：

uv add git+https://github.com/encode/httpx --branch main
5.3.2.3 --rev <REV>

或者，版本（提交）：

uv add git+https://github.com/encode/httpx --rev 326b9431c761e1ef1e00b9f760d1f654c8db48c6
5.3.2.4 subdirectory=

如果包不在仓库根目录，可以指定 subdirectory：

uv add git+https://github.com/langchain-ai/langchain#subdirectory=libs/langchain

[project]
dependencies = ["langchain"]

[tool.uv.sources]
langchain = { git = "https://github.com/langchain-ai/langchain", subdirectory = "libs/langchain" }

5.3.3 URL

要添加 URL 源，请提供指向 wheel 文件（以 .whl 结尾）或源分发包（通常以 .tar.gz 或 .zip 结尾；有关所有支持的格式，请参阅此处）的 https:// URL。

例如：

uv add "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz"

这将生成一个 pyproject.toml 文件，内容如下：

[project]
dependencies = ["httpx"]

[tool.uv.sources]
httpx = { url = "https://files.pythonhosted.org/packages/5c/2d/3da5bdf4408b8b2800061c339f240c1802f2e82d55e50bd39c5a881f47f0/httpx-0.27.0.tar.gz" }

也可以使用 { url = <url> } 语法在 pyproject.toml 中手动添加或编辑 URL 依赖项。如果源分发包不在归档文件的根目录中，可以指定 subdirectory。

5.3.4 路径

要添加路径源，请提供 wheel 文件（以 .whl 结尾）、源发行版（通常以 .tar.gz 或 .zip 结尾；有关所有支持的格式，请参阅此处）的路径，或包含 pyproject.toml 的目录的路径。

例如：

uv add /example/foo-0.1.0-py3-none-any.whl

这将生成一个 pyproject.toml 文件，内容如下：

[project]
dependencies = ["foo"]

[tool.uv.sources]
foo = { path = "/example/foo-0.1.0-py3-none-any.whl" }

路径也可以是相对路径：

uv add ./foo-0.1.0-py3-none-any.whlpo

或者，是项目目录的路径：

uv add ~/projects/bar/

5.4 依赖解析

此类参数用于调整依赖版本的解析逻辑（如是否升级、是否允许预发布版），适配不同场景的版本稳定性需求。

5.4.1 -U, --upgrade

  • 作用：允许升级已安装的依赖（忽略 uv.lock 中的固定版本），并刷新缓存，适用于主动更新依赖到最新版。

  • 隐含：自动启用 --refresh（刷新缓存）。

  • 使用案例：升级已安装的 requests 到最新版（忽略当前锁定的版本）：

    uv add --upgrade requests

5.4.2 -P, --upgrade-package <UPGRADE_PACKAGE>

  • 作用：仅升级“指定的单个/多个依赖”（不升级其他依赖），精细化控制升级范围，避免批量升级导致冲突。

  • 隐含：自动启用 --refresh-package（刷新指定包的缓存）。

  • 使用案例：仅升级 requests 和 urllib3，不影响其他依赖（如 flask）：

    uv add --upgrade-package requests --upgrade-package urllib3

5.4.3 --resolution <RESOLUTION>

  • 作用：指定依赖版本的“解析策略”，控制选择哪个版本的依赖。

  • 可选值：

    • highest：选择最高可用版本（默认，适合追求最新功能）

    • lowest：选择最低兼容版本（适合稳定性优先，如旧项目）

    • lowest-direct：直接依赖选最低版本，间接依赖选兼容版本

  • 环境变量：UV_RESOLUTION。

  • 使用案例：为旧项目安装 flask，选择“最低兼容版本”（确保与旧代码兼容）：

    uv add --resolution lowest flask

5.4.4 --prerelease <PRERELEASE>

  • 作用：控制是否允许安装“预发布版本”（如 1.0.0a1、2.0.0rc2）。

  • 可选值：

    • disallow：禁止（默认，仅稳定版）

    • allow：允许所有预发布版

    • if-necessary：仅当无稳定版时允许

    • explicit：仅当包名指定预发布版时允许（如 fastapi==0.100.0rc1）

  • 环境变量：UV_PRERELEASE。

  • 使用案例：安装 fastapi 的预发布版（体验最新功能）：

    uv add --prerelease allow fastapi

5.4.5 --exclude-newer <EXCLUDE_NEWER>

  • 作用：仅安装“指定日期前上传到 PyPI 的版本”，避免下载过新的版本（如规避刚发布的 bug 版本）。

  • 格式：YYYY-MM-DD（如 2024-01-01）

  • 环境变量：UV_EXCLUDE_NEWER。

  • 使用案例：仅安装 2024 年 5 月 1 日前上传的 requests 版本（避免 5 月后可能的问题版本）：

    uv add --exclude-newer 2024-05-01 requests

5.4.6 --no-sources

  • 作用：忽略 pyproject.toml 中 tool.uv.sources 配置的本地/工作区依赖，仅从官方索引或指定索引下载依赖，适用于验证“发布版本的依赖兼容性”。

  • 使用案例：忽略本地工作区依赖，仅从 PyPI 安装 my-project 的依赖（模拟用户安装场景）：

    uv add --no-sources my-project

5.5 安装选项

此类参数用于调整依赖的安装行为（如是否重装、链接方式），优化安装速度或磁盘占用。

5.5.1 --reinstall

  • 作用：强制重新安装所有依赖（无论是否已安装），适用于修复安装损坏的包（如 .pyc 文件丢失）。

  • 隐含：自动启用 --refresh（刷新缓存）。

  • 使用案例：重新安装 numpy（修复可能的安装损坏）：

    uv add --reinstall numpy

5.5.2 --reinstall-package <REINSTALL_PACKAGE>

  • 作用：仅重新安装“指定的单个/多个依赖”（不影响其他依赖），精细化修复安装问题。

  • 隐含：自动启用 --refresh-package（刷新指定包的缓存）。

  • 使用案例：仅重新安装 pandas（其他依赖如 requests 保持不变）：

    uv add --reinstall-package pandas

5.5.3 --link-mode <LINK_MODE>

  • 作用：指定从全局缓存到虚拟环境的“链接方式”，影响安装速度和磁盘占用。

  • 可选值：

    • symlink：符号链接（最快，占空间最小，跨文件系统可能失效）

    • hardlink：硬链接（较快，占空间小，仅同文件系统可用）

    • copy：复制文件（最慢，占空间大，兼容性最好）

    • clone：克隆（类似 copy，但支持硬链接优化）

  • 环境变量：UV_LINK_MODE。

  • 使用案例：用“硬链接”方式安装 torch（节省磁盘空间，且避免符号链接跨盘问题）：

    uv add --link-mode hardlink torch==2.1.2

5.5.4 --compile-bytecode

  • 作用：安装后自动将 Python 源码（.py）编译为字节码（.pyc），加速后续脚本启动速度（避免首次运行时编译）。

  • 环境变量：UV_COMPILE_BYTECODE。

  • 使用案例：安装 django 并编译字节码（加速项目启动）：

    uv add --compile-bytecode django

5.6 构建选项

此类参数用于处理“需从源码编译的依赖”（如 C/C++ 扩展包），调整构建过程的隔离性和参数。

5.6.1 -C, --config-setting <CONFIG_SETTING>

  • 作用：向 PEP 517 构建后端（如 setuptools）传递构建参数（如编译选项），适用于需自定义编译的 C/C++ 包。

  • 格式：KEY=VALUE（如 cmake_args=-DCMAKE_BUILD_TYPE=Release）。

  • 使用案例：安装需 CMake 编译的 my-cpp-package，传递“Release 模式”的编译参数：

    uv add --config-setting "cmake_args=-DCMAKE_BUILD_TYPE=Release" my-cpp-package

5.6.2 --no-build-isolation

  • 作用：禁用“构建隔离”（默认启用），即不创建单独的虚拟环境安装构建依赖（如 setuptools、wheel），直接使用当前环境的构建工具，适用于自定义构建环境。

  • 环境变量：UV_NO_BUILD_ISOLATION。

  • 使用案例：禁用构建隔离，使用当前环境的 setuptools 编译安装 my-package：

    uv add --no-build-isolation my-package

5.6.3 --no-binary

  • 作用：不使用预编译的 wheel 包，强制从源码编译安装所有依赖，适用于需自定义编译选项或无对应 wheel 包的场景（如 ARM 架构）。

  • 环境变量：UV_NO_BINARY。

  • 使用案例：强制从源码编译安装 requests（不使用 PyPI 上的 wheel 包）：

    uv add --no-binary requests

5.6.4 其他构建控制参数

参数 作用 使用案例
--config-settings-package <CONFIG_SETTING_PACKAGE> 为“指定包”单独传递构建参数（格式：PACKAGE:KEY=VALUE） uv add --config-settings-package "my-cpp-package:cmake_args=-DCMAKE_BUILD_TYPE=Debug" my-cpp-package other-package
--no-build-isolation-package <NO_BUILD_ISOLATION_PACKAGE> 仅为“指定包”禁用构建隔离 uv add --no-build-isolation-package my-package other-package
--no-build 不构建源码包（若依赖仅提供源码，会报错） uv add --no-build requests（仅当 requests 有 wheel 包时生效）
--no-build-package <NO_BUILD_PACKAGE> 仅为“指定包”禁用构建（不编译其源码） uv add --no-build-package my-package other-package
--no-binary-package <NO_BINARY_PACKAGE> 仅为“指定包”不使用 wheel 包（强制源码编译） uv add --no-binary-package numpy pandas（仅 numpy 从源码编译）

5.7 缓存选项

此类参数用于管理 uv 的全局缓存（默认路径如 ~/.cache/uv），控制是否使用缓存、刷新缓存或自定义缓存目录。

5.7.1 -n, --no-cache

  • 作用：完全不使用全局缓存，也不写入缓存，临时使用一个独立的临时目录存储依赖，适用于避免缓存污染（如测试环境）。

  • 环境变量：UV_NO_CACHE。

  • 使用案例：不使用缓存，临时安装 requests（安装后临时目录会删除）：

    uv add --no-cache requests

5.7.2 --cache-dir <CACHE_DIR>

  • 作用：自定义全局缓存目录（替代默认路径），适用于磁盘空间不足或需指定缓存位置的场景。

  • 环境变量：UV_CACHE_DIR（示例：P:\uv_cache）。

  • 使用案例：将缓存目录设为 D:\uv-cache，并安装 torch（缓存文件存于该目录）：

    uv add --cache-dir D:\uv-cache torch

5.7.3 --refresh

  • 作用：刷新全局缓存中的所有依赖（重新下载最新版本的缓存），适用于缓存过期或怀疑缓存损坏的场景。

  • 隐含：若同时使用 --upgrade，自动启用 --refresh。

  • 使用案例：刷新缓存并安装 requests（确保使用最新的缓存版本）：

    uv add --refresh requests

5.7.4 --refresh-package <REFRESH_PACKAGE>

  • 作用：仅刷新“指定依赖”的缓存（不影响其他缓存），精细化更新缓存。

  • 使用案例：仅刷新 flask 的缓存，其他依赖（如 requests）保持缓存不变：

    uv add --refresh-package flask

5.8 Python 选项

此类参数用于指定安装依赖时使用的 Python 版本或解释器路径，适配多 Python 版本的项目。

5.8.1 -p, --python <PYTHON>

  • 作用：指定用于解析和安装依赖的 Python 解释器（支持版本号、路径或别名）。

  • 支持格式：

    • 版本号：3.10、3.11.6（uv 会自动查找或下载对应版本）

    • 路径：C:\Python310\python.exe、/usr/bin/python3.11

    • 别名：python3、py3.10

  • 环境变量：UV_PYTHON。

  • 使用案例：使用 Python 3.10 解释器安装 django（确保与项目 Python 版本匹配）：

    uv add --python 3.10 django

5.8.2 --managed-python

  • 作用：强制使用 uv 自身管理的 Python 版本（不使用系统 Python），适用于统一开发环境的 Python 版本。

  • 环境变量：UV_MANAGED_PYTHON。

  • 使用案例：强制使用 uv 管理的 Python 3.11 安装 fastapi：

    uv add --managed-python 3.11 fastapi

5.8.3 --no-python-downloads

  • 作用：禁止 uv 自动下载 Python 版本（若指定的 Python 版本不存在，会报错），适用于不允许联网下载的环境。

  • 环境变量：UV_PYTHON_DOWNLOADS=never。

  • 使用案例：禁止自动下载 Python，使用已有的 Python 3.9 安装 pandas（若 3.9 不存在则报错）：

    uv add --no-python-downloads --python 3.9 pandas

5.8.4 --no-managed-python

  • 作用：禁用 uv 管理的 Python 版本，仅使用系统已安装的 Python，适用于需依赖系统 Python 环境的场景。

  • 环境变量：UV_NO_MANAGED_PYTHON。

  • 使用案例：仅使用系统 Python（不使用 uv 管理的版本）安装 requests：

    uv add --no-managed-python requests

5.9 全局选项

此类参数是 uv 所有命令的通用选项，控制工作目录、输出日志、网络模式等。
-q, --quiet 安静输出（减少日志，仅显示错误） uv add --quiet requests（不显示安装进度和详情）
-v, --verbose 详细输出（显示更多日志，如依赖解析过程） uv add --verbose django（排查安装失败原因）
--color <COLOR_CHOICE> 控制输出颜色（auto/always/never） uv add --color never requests（终端不支持颜色时禁用）
--offline 离线模式（仅使用缓存，不联网） uv add --offline requests（无网络时从缓存安装）
--allow-insecure-host <ALLOW_INSECURE_HOST> 允许向指定主机发送不安全 HTTP 请求（不验证 TLS） uv add --allow-insecure-host private-pypi.example.com --index http://private-pypi.example.com/simple/ my-package
--no-progress 隐藏所有进度条（仅显示结果） uv add --no-progress torch（避免进度条干扰日志）
--directory <DIRECTORY> 切换到指定目录后执行命令（等价于 cd 目录 && uv add） uv add --directory ./my-django-project django（在 my-django-project 目录安装）
--project <PROJECT> 指定项目目录（优先于 --directory，关联项目配置） uv add --project ./my-flask-app flask（以 my-flask-app 为项目根目录）
--config-file <CONFIG_FILE> 指定自定义 uv.toml 配置文件（替代默认配置） uv add --config-file ./my-uv.toml requests（使用自定义配置）
--no-config 忽略所有配置文件（pyproject.toml/uv.toml） uv add --no-config requests（不使用项目配置，用默认值）
-h, --help 显示 uv add 命令的详细帮助（含所有参数说明） uv add --help（查看完整文档）

6. 删除依赖项

要删除依赖项：

uv remove httpx

具体参数与上节（uv）类似：可以使用 --dev、--group 或 --optional 标志从特定表中删除依赖项。

如果为要删除的依赖项定义了源，并且没有其他对该依赖项的引用，那么该源也将被删除。

7. 更改依赖项

要更改现有依赖项，例如，为 httpx 使用不同的约束条件：

uv add "httpx>0.1.0"

在这个示例中，我们正在更改 pyproject.toml 中依赖项的约束条件。 只有在必要时，为满足新的约束条件，依赖项的锁定版本才会更改。要强制将包版本更新为约束范围内的最新版本，请使用 --upgrade-package <name>，例如：

uv add "httpx>0.1.0" --upgrade-package httpx

请求不同的依赖源将更新 tool.uv.sources 表，例如，在开发期间从本地路径使用 httpx：

uv add "httpx @ ../httpx"

8. 特定平台的依赖项

例如，要在 Linux 上安装 jax，但不在 Windows 或 macOS 上安装：

uv add "jax; sys_platform == 'linux'"

生成的 pyproject.toml 将在依赖项定义中包含环境标记：

[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.11"

dependencies = ["jax; sys_platform == 'linux'"]

同样，要在 Python 3.11 及更高版本中包含 numpy：

uv add "numpy; python_version >= '3.11'"
# python # uv # 开发语言
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

靠谱的 ai智能外呼电话机器人推荐

avatar AI Agent技术社区
cover

AI智能外呼系统如何让企业在拓客方面取得实效？—2026年十大电销机器人深度测评

avatar AI Agent技术社区

AI Agent 的能力从哪里来？一文讲清后训练、上下文学习和外部能力

当我们看到一个 Agent 表现得越来越“聪明”时，不妨换一个角度去理解它。有些能力来自模型长期训练形成的基本功；有些能力来自当前上下文中的规则、示例和任务约束；还有一些能力来自运行时连接的知识库、工具和业务系统。从工程视角来看，现代 Agent 已经不再只是一个大模型，而是一套围绕大模型构建的系统。模型负责推理，Context 负责任务适配，外部系统负责提供知识、状态与执行能力。真正决定 Age

avatar AI Agent技术社区