uv整合六大功能：包管理（替代 pip）、虚拟环境（替代 virtualenv）、Python 版本控制（替代 pyenv）、依赖锁定（替代 poetry）、工具安装（替代 pipx）、包发布（替代 twine）。

有了uv，这一切都变得简单起来。只需执行“uv add”命令，即可轻松添加项目依赖，并自动生成结构清晰的“pyproject.toml”文件。uv能智能处理相关依赖关系，让工作效率显著提升。

uv提供了全面的项目管理功能，包括使用通用锁文件（uv.lock）来锁定项目的依赖版本，以确保在不同环境下项目的一致性。此外，通过“uv init example”命令，您可以轻松在指定路径下创建一个新的项目。对于已有“pyproject.toml”文件的uv项目，可以直接使用“uv sync”命令来自动创建虚拟环境并下载依赖。

当您创建新脚本时，只需使用 “uv add –script example.py requests”命令为脚本添加依赖，然后运行“uv run example.py”即可。uv会自动在隔离的虚拟环境中安装所需的包并运行脚本，确保脚本开发与系统环境相互独立且无冲突。

uv不仅提供了丰富的命令行工具来执行和安装Python包，还具备类似pipx的功能。这使得开发者能够更便捷地使用和管理Python工具和包。

优点

• 一个工具即可替代 pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv 等。
• 比 pip 快 10-100 倍。
• 安装和管理 Python 版本。
• 运行和安装 Python 应用程序。
• 运行脚本，支持内联依赖元数据。
• 提供全面的项目管理，带有通用的锁定文件 (lockfile)。
• 包含一个兼容 pip 的接口，在熟悉的 CLI 中获得性能提升。
• 支持 Cargo 风格的工作区 (workspaces)，适用于可扩展的项目。
• 节省磁盘空间，具有用于依赖项去重的全局缓存。
• 可以通过 curl 或 pip 安装，无需 Rust 或 Python。
• 支持 macOS、Linux 和 Windows。

缺点

• 无法取代 Conda 的所有功能：对于那些需要系统级依赖的场景，UV 无能为力。
• 生态系统的新进入者，成熟度有待验证：UV 于 2024 年才推出，迄今仍属于相当新的项目。
• 学习成本和观念转换：对于习惯了现有 pip/Conda 工作流的开发者，转换到 UV 需要一些学习和观念更新。
• 非致命但存在的功能缺失：虽然 UV 力求兼容 pip，但仍有少数 pip 功能目前不受支持或者行为不同。

适用场景

在以下情况下优先思考使用 UV：

• 纯 Python 项目，需要更快的依赖安装；
• 大型或复杂依赖树的项目；
• 需要简化开发环境管理；
• 频繁构建/销毁环境的场景；
• 多 Python 版本管理。

安装

独立安装

MACOS/Linu环境

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

Windows环境

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

pip/pipx安装

尽管 uv 本身不依赖 Python 环境，但官方也在PyPI发布了uv。推荐使用pipx将其隔离安装：

  # pip
  pip install uv

或者

  # pipx
  pipx install uv

更新

  # 如果通过独立安装程序安装，uv 可以更新到最新版本：
  uv self update

项目目录基本结构

在讲述 uv 命令前，先来了解使用 uv创建的项目的一般目录结构。使用 uv init创建新项目后包含pyproject.toml、README.md、.gitignore、.python-version等文件，结构如下：

  .
  ├── .venv
  │   ├── Scripts
  │   ├── lib
  │   └── pyvenv.cfg
  ├── .python-version
  ├── README.md
  ├── main.py
  ├── pyproject.toml
  └── uv.lock

项目由几个部分组成，它们协同工作，让 uv 更好的管理项目。

使用 uv init 创建项目时不会创建 .venv目录和uv.lock文件，而是在uv 第一次运行 uv 命令（例如 uv run, uv sync, uv lock, uv add等）时在项目根目录下创建项目虚拟环境（.venv）和锁定文件（uv.lock）。

pyproject.toml文件

pyproject.toml 包含有关项目的元数据：

  [project]
  name = "hello-world"
  version = "0.1.0"
  description = "Add your description here"
  readme = "README.md"
  dependencies = []

您将使用此文件指定依赖项，以及有关工程的详细信息，例如其描述或许可证。可以手动编辑此文件，也可以使用 uv add 和 uv remove 从终端管理您的项目。

.python-version文件

.python-version 文件可用于创建默认的python版本请求。uv在工作目录及其每个父目录中搜索 .python-version 文件。如果没有找到，uv将使用上述任何请求格式检查用户级配置目录。但提议使用版本号以与其他工具互操作。

• 可以使用 uv python pin 在当前目录中创建 .python-version 文件。
• 可以使用 uv python pin–global 在用户配置目录中创建全局的 .python-version 文件。
• 可以通过 –no config 参数指定禁用 .python-version 文件。 uv不会搜索超出项目或工作区边界的 .python-version 文件（用户配置目录除外）。

uv.lock文件

uv.lock 是一个跨平台的 锁定文件，其中包含有关项目依赖项的确切信息。与用于指定项目的广泛要求的pyproject.toml不同，锁定文件包含项目环境中安装的确切解析版本。此文件应签入版本控制中，以便跨计算机进行一致且可重复的安装。

uv.lock是一个可读的 TOML 文件，但由 uv 管理，不应手动编辑。

在每次 uv run 调用之前，uv 将验证锁定文件 uv.lock 是否更新了 pyproject.toml 中的配置，无需手动干预即可保持项目同步。uv run 可保证您的命令在一致、锁定的环境中运行。

  小提示！
  如果目前已有现有项目中引入 UV，也超级简单。假设项目已有 requirements.txt 列出了依赖，
  可以直接用 UV 安装。
  
  切换到已有项目目录
  uv venv         # (可选)手动创建虚拟环境，若不提前创建，下一步也会自动创建
  uv pip install -r requirements.txt

uv pip install的用法与普通pip完全一样，但利用了 UV 的高速引擎。

安装完成后，也可以运行uv lock生成锁定文件，后来改用 UV 来维护依赖。值得一提的是，UV 创建的虚拟环境位于项目目录下（默认命名为 .venv），您也可以通过传统方式激活这个环境并运行 Python。不过，大部分情况下直接用uv run或uv exec（执行任意shell命令于虚拟环境中）就足够了。

.venv目录

.venv目录包含项目的虚拟环境，使得项目所需的Python环境独立于系统环境的其他部分如其他项目。这也是 uv 安装的依赖所放置的区域目录。

Python版本条件格式

安装和管理Python的版本。uv支持以下版本格式：

• version> 如 3, 3.12, 3.12.3)
• <version-specifier> (如 >=3.12,<3.13)
• <implementation> (如 cpython or cp)
• <implementation>@<version> (如 cpython@3.12)
• <implementation><version> (如 cpython3.12 or cp312)
• <implementation><version-specifier> (如 cpython>=3.12,<3.13)
• <implementation>–<version>–<os>–<arch>–<libc> (如 cpython-3.12.3-macos-aarch64-none)

此外，可以使用以下命令请求特定的Python解释器：

• <executable-path> 指定执行路径如 /opt/homebrew/bin/python3
• <executable-name> 指定执行名称如 mypython3
• <install-dir> (指定安装环境如 /some/environment/

默认的，如果在系统中没有找到指定的Python版本，uv会自动下载安装；如果使用 uv python install 未指定任何版本，uv将安装最新的版本。

路径查找原则

uv查找路径遵循以下原则：

• 被管理的Python安装路径 UV_PYTHON_INSTALL_DIR.
• Python接收器路径 PATH 如macOS或Linux环境下的python, python3 或 python3.x ；windows环境下的 python.exe 。
• Windows环境下, Python执行器会被写入到注册表中，Windows会匹配到请求的版本 (可参见py –list-paths) 。

常用命令

uv 的基本用法围绕着uv <动作> <对象>展开：使用uv add/remove管理依赖，uv run运行代码，uv install安装工具，uv lock锁定版本等等。其命令体系参考了 pip/poetry 等的常用形式，易于理解。在实际操作中，uv 将显著减少您手动管理虚拟环境和依赖的细节，把精力更多聚焦在代码本身。

Python管理

uv 安装 Python，并允许快速切换版本。

01、uv python install

下载和安装Python版本。支持 CPython 和 PyPy 。Python版本将被安装到uv管理的Python目录下，可以使用 uv python dir 检索。python解释器文件不是全局可用的，托管给uv的python版本仅在uv命令或活动虚拟环境中使用。

用法： uv python install [OPTIONS] [TARGETS]

 # 安装指定的具体版本
 $ uv python install 3.12.3
 
 # 安装指定主版本下的最新补丁版本
 $ uv python install 3.12
 
 # 安装指定条件下的Python版本
 $ uv python install '>=3.8,<3.10'
 
 # 安装多个 Python 版本
 $ uv python install 3.10 3.11 3.12
 
 # 安装特定的实现
 $ uv python install pypy
 
 # 安装预览版本
 $ uv python install 3.12 --preview
 
 #以上命令将Python 3.12最新升级版本安装到 `~/.local/bin` 目录下。如果 `~/.local/bin` #不存在，可以使用 `uv tool update-shell` 添加。
 #如果以上命令中包含 `--default` 参数，如果要要下载的Python执行器版本在uv的管理之下，将重新覆盖该版本；如果不在uv管理下，如果使用 `--force` 参数，则也会覆盖掉该版本，如果没有则不会做覆盖处理。
 $ uv python install 3.12 --default --preview
 # 或者
 $ uv python install 3.12 --default --preview --force
 
 # 重新安装版本
 #如果需要安装，则在原有安装命令行上增加 `--reinstall` 即可。如：
 $ uv python install --reinstall

02、uv python list

列出可用的Python安装版本。默认下载最新的可用更新版本并安装。使用 –managed-python 则仅查看托管的python版本；使用 –no-managed-python 则忽略托管的python版本；使用 –all-versions 则查看所有可用的补丁版本；使用 –only-installed 则忽略可用的下载。

用法：uv python list [OPTIONS] [REQUEST]

 # 列出已安装的可用的所有Python版本
 $ uv python list
 
 # 列出指定的已安装且可用的Python版本
 $ uv python list 3.13
 
 # 列出所有Python版本
 $ uv python list --all-versions
 
 # 列出所有其他平台的Python版本
 $ uv python list --all-platforms
 
 # 仅列出已安装的Python版本
 $ uv python list --only-installed

03、uv python find

查找安装的Python版本，显示Python解释器的路径。

用法：uv python find [OPTIONS] [REQUEST]

 # 查找Python解释器
 $ uv python find
 
 # 查找符合版本条件的Python解释器
 $ uv python find '>=3.11'
 
 # `uv python find`查找结果包含虚拟环境安装的Python版本。如果工作目录（即项目目录）下包含 `.venv`目录，或者所有上级目录，或者设置了 `VIRTUAL_ENV` 环境变量，则会列出以上所有符合条件的版本。
 
 # 如果需要忽略虚拟环境下安装的版本，需要添加 `--system` 参数 
 $ uv python find --system

04、uv python pin

固定到特定的Python版本。使用该命令，将Python版本写入到 .python-version 文件中，为其他的uv命令指定所需的Python版本。

用法：uv python pin [OPTIONS] [REQUEST]

 uv python pin

05、uv pyton dir

显示uv管理的Python安装目录，默认情况下，Python将被安装到uv的数据目录下（Linux环境默认为 XDG_DATA_HOME/uv/python 或
HOME/.local/share/uv/python 目录；Windows环境默认在 %APPDATA%uvdatapython ）。

uv管理的Python安装目录可以通过设置环境变量 $UV_PYTHON_INSTALL_DIR 来修改。

用法：uv python dir [OPTIONS]

 uv python dir

06、uv python uninstall

卸载Python版本。

用法：uv python uninstall [OPTIONS] <TARGETS>…

 uv python uninstall

脚本支持

通过uv，可以执行标准的Python脚本。

01、uv run

执行Python脚本，与 项目管理 中的 uv run 的一样。

02、uv add –script

添加依赖到脚本，与 项目管理 中的 uv add 的一样。

03、uv remove –script

从脚本中删除依赖，与 项目管理 中的 uv remove 的一样。

项目管理

01、uv init

创建新项目。创建时将遵循pyproject.toml文件定义规则。

如果pyproject.toml已存在，uv将抛出错误并退出；如果pyproject.toml文件在待创建项目路径的任何上级路径中找到，则该项目将添加到上级目录的命名空间中。

使用uv init 创建一个新项目并创建虚拟环境。uv init会在创建项目目录下创建一个包含pyproject.toml、README.md、.gitignore、.python-version等文件的项目结构。

项目中的虚拟环境创建（创建 .venv 目录）和创建锁文件（uv.lock)不会在第一次创建项目时创建。

用法：uv init [OPTIONS] [PATH]

 # 创建新项目beta
 $ uv init beta
 # 进入新创建的项目目录
 $ cd beta

另外一种创建方式，可以先创建目录，然后进入新建目录后创建项目。

 $ mkdir hello-world
 $ cd hello-world
 $ uv init

构建项目的文件结果如下：

 .
 ├── .python-version
 ├── README.md
 ├── main.py
 ├── pyproject.toml

创建的 main.py脚本文件是实现简单的“helloword”的样例，可以使用 uv run 运行看看效果。

 $ uv run main.py
 Hello from beta

02、uv add

为项目添加依赖。项目中添加的依赖信息会被写入到项目的 pyproject.toml文件中。

如果添加的依赖已存在，如果待添加的依赖和已存在的依赖的版本号一样，则更新。

如果给定的依赖已经存在，它将被更新为新的版本，除非它包含与现有不同，在这种情况下，将添加该依赖为新的依赖。

如果没有约束项或者依赖项的URL有效，则添加该依赖的最新兼容依赖的最低版本，例如>=1.2.3。如果使用了 –frozen 则不执行解析。

在添加依赖时，锁定文件（uv.lock）和项目的虚拟环境将会被更新。但是，如果使用 –frozen 参数则不会跟你更新锁定文件；如果使用了 –no-sync 参数，则不会更新项目环境。

uv将在当前目录或当前目录的上级目录中搜索项目。如果找不到项目，uv将退出并显示错误。

用法：uv add [OPTIONS] <PACKAGES|–requirements <REQUIREMENTS>>

 $ cd beta # 进入项目根目录
 $ uv add ruff # 添加依赖ruff
 
 Using CPython 3.12.8
 Creating virtual environment at: .venv
 Resolved 2 packages in 3.87s
 Prepared 1 package in 4.20s
 Installed 1 package in 476ms
 
 + ruff==0.9.1

03、uv remove

将依赖从工程里移除，同时依赖也会从 pyproject.toml文件里移除。

用法：uv remove [OPTIONS] <PACKAGES>…

 uv remove ruff

04、uv sync

更新项目的虚拟环境。即同步项目所有的依赖项和更新锁定文件的更新日期。

如果未使用 –locked 或 –frozen 参数，项目将会在同步前重新锁定。

如果项目中不存在虚拟环境（.venv)，则会创建它；

如果在当前工作路径或者该路径下的所有上级目录的任一级下都未找到指定的同步项目，uv将报告错误并退出。

用法：uv sync [OPTIONS]

 uv sync
 source .venv/Scripts/activate
 flask run -p 3000
 python example.py

05、uv lock

更新项目的锁定文件。如果项目中没有锁定文件（uv.lock）,该文件将被创建；否则该锁定文件内容将作为使用第一。如果项目依赖没有变化，锁定动作不会影响锁定文件，除非参数 –upgrade 被使用。

用法：uv lock [OPTIONS]

 $ uv lock --upgrade-package requests

06、uv run

执行命令或者脚本。运行时要确保命令允许在Python环境下。

当执行的文件扩展名为.py或为HTTP（S）连接时，将被视为脚本并使用Python解释器运行，即 uv run file.py 等效于 uv run Python file.py。对于URL，执行前会临时下载。如果下载脚本包含内联依赖元数据，它将被安装到一个隔离的、短暂的环境中。当与 – 一起使用时，将从stdin读取输入，并将其视为Python脚本。

当在项目中使用，在调用命令前创建和更新项目虚拟环境。

当在项目外部使用时，如果在当前目录或父目录中可以找到虚拟环境，则该命令将在该环境中运行。否则，该命令将在检索到的Python解释器环境中运行。

用法：uv run [OPTIONS] [COMMAND]

 $ uv run ruff check
 All checks passed!

07、uv tree

显示项目依赖关系树。

用法：uv run [OPTIONS] [COMMAND]

 uv tree

08、uv build

将Python包构建到源代码发行版和二进制发行版（“wheel”）中。

uv build 接受一个目录或源代码分发的路径，默认为当前工作目录。默认情况下，如果给定的是一个目录，uv build 将从源目录构建一个源代码发行版（“sdist”），并依据源发行版构建一个二进制发行版（”wheel”）。

uv build –sdist 可用于仅构建源代码发行版，uv build –Wheel 可用于仅生成二进制发行版，而 uv build –sdist –wheel 则可用于依据源代码构建这两个发行版即源代码发行版和二进制发行版。

如果给定的是源代码发行版，uv build –wheel 将依据源代码发行版构建二进制发行版。

用法：uv build [OPTIONS] [SRC]

 $ uv build
 $ ls dist/

09、uv publish

上传发行版本到指定目标目录中。

用法：uv publish [OPTIONS] [FILES]…

 $ uv publish

• 通过 –token 携带PYPI的token或者通过环境变量 UV_PUBLISH_TOKEN 设置token；
• 通过 –username 携带PYPI的用户名或者通过环境变量 UV_PUBLISH_USERNAME 设置用户名；
• 通过 –password 携带PYPI的用户密码或者通过环境变量 UV_PUBLISH_PASSWORD 设置用户密码。

• 如果从github发布到PYPI，则不需要设置任何认证信息，只需要在PYPI的远程项目上添加发布者的授信信息即可。

如果要通过[[tool.uv.index]]发布，则将发布地址配置到 publish-url 参数，然后使用 uv publish –index <name>来发布，示例如下

 [[tool.uv.index]]
 name = "testpypi"
 url = "https://test.pypi.org/simple/"
 publish-url = "https://test.pypi.org/legacy/"
 explicit = true

工具管理

01、uv tool run

执行Python包提供的命令。默认情况下，假定要安装的包与命令名匹配。

命令的名称可以为 <package>@<version> 包含详细版本的格式，例如 uv tool runruff@0.3.0 。如果需要更复杂的版本规范，或者命令由不同的包提供，则使用 –from。

uvx 可用于调用Python，例如，使用 uvx –Python 或 uvx –Python@<version>。Python解释器将在隔离的虚拟环境中启动。

如果该工具之前已安装，即通过 uv tool install 安装，则使用已安装的版本，除非请求了版本或使用了 –isolated 参数。

uvx 是作为 uv tool run的别名提供的，它们的处理结果是一样的。

如果没有提供命令，则显示已安装的工具。如果提供，软件包被安装到uv缓存目录中的临时虚拟环境中。

用法：uv tool run [OPTIONS] [COMMAND]

 uv tool run ruff
 #或
 uvx ruff

02、uv tool install

安装Python包提供的命令。

工具包被安装到uv工具目录中的隔离虚拟环境中。可执行文件链接到工具可执行目录，该目录遵循 XDG 标准约定，可以使用 uv tool dir –bin 检索。

如果之前安装了该工具，该工具将会被替换。

用法：uv tool install [OPTIONS] <PACKAGE>

 $ uv tool install ruff
 Resolved 1 package in 1.32s
 Installed 1 package in 14ms
 
  + ruff==0.9.1
    Installed 1 executable: ruff.exe
 
 $ ruff --version
 ruff 0.9.1

03、uv tool upgrade

升级已安装的工具。 如果工具安装时有版本限制，则升级时会遵守这些限制（升级的工具超出最初提供的限制，再次使用 uv tool install）。 如果工具安装时具有特定设置，则升级时将遵守这些设置。例如，如果在安装过程中设置了 –prereleases-allow 参数，则升级时将继续遵守它。

用法：uv tool upgrade [OPTIONS] <NAME>…

 # 更新ruff到最新版本
 $ uv tool upgrade ruff
 # 更新所有工具到最新版本
 $ uv tool upgrade --all
 #
 $ uv tool upgrade black --upgrade-package click

04、uv tool list

列出已安装的工具。

用法：uv tool list [OPTIONS]

 $ uv tool list

05、uv tool uninstall

卸载已安装的工具。

用法：uv tool uninstall [OPTIONS] <NAME>…

 $ uv tool uninstall ruff

06、uv tool update-shell

确保工具可执行目录在 PATH 上。 如果 PATH 中不存在工具可执行目录，uv将尝试将其添加到相关的shell配置文件中。 如果shell配置文件已经包含工具可执行目录的说明，但该目录不在 PATH 中，uv将退出并报错。 工具可执行目录遵循XDG标准规定，可以使用 uv tool dir –binV检索。

用法：uv tool update-shell [OPTIONS]

 uv tool update-shell

07、uv tool dir

显示uv工具目录的路径。 工具目录用于存储已安装工具的环境和元数据。 默认情况下，工具存储在uv数据目录中（Unix上为 XDG_data_HOME/uv/tools 或
HOME/.local/share/uv/tools，在Windows上为 %APPDATA%uvdata ools)。 工具安装目录可能通过设置环境变量 UV_TOOL_DIR设置并覆盖。

用法：uv tool dir [OPTIONS]

 $ uv tool dir

venv和 virtualenv的可替代命令

通过uv venv为项目手工创建所需的虚拟环境

01、uv venv

创建一个虚拟环境。默认在当前工作目录下创建一个命名为 .venv目录的虚拟环境。如果要改变虚拟环境，可以通过设置环境变量 UV_PROJECT_ENVIRONMENT 来实现；但只能从项目根目录运行时才有效。

如果在指定目标路径下已经存在虚拟环境，则架构删除掉原有的虚拟环境并新建一个空的虚拟环境 .venv。

用法：uv venv [OPTIONS] [PATH]

 # 创建虚拟环境并指定项目所需要的Python解释器为3.12.0版本
 # 并将激活和撤销激活命令放置到虚拟环境 .venv目录下的Scripts目录中
 $ uv venv --python 3.12.0
 Using CPython 3.12.0
 Creating virtual environment at: .venv
 Activate with: .venvScriptsactivate

02、activate

激活当前项目虚拟环境。

用法：activate

进入当前项目目录下，执行：

 .venvScriptsactivate

03、deactivate

退出虚拟环境。

用法：deactivate

进入当前项目目录，然后执行

 $ .venvScriptsdeactivate

pip和 pipdeptree的可替代命令

01、uv pip install

安装依赖包到当前的项目的虚拟环境中，

用法：uv pip install [OPTIONS] <PACKAGE|–requirements <REQUIREMENTS>|–editable <EDITABLE>|–group <GROUP>>

 $ uv pip install "flask[dotenv]"
 $ uv pip install flask ruff
 $ uv pip install 'ruff>=0.2.0' 

02、uv pip uninstall

从当前项目的虚拟环境中卸载指定的依赖项。

用法：uv pip uninstall [OPTIONS] <PACKAGE|–requirements <REQUIREMENTS>>

 $ uv pip uninstall flask
 $ uv pip uninstall flask ruff

03、uv pip freeze

按需求的格式列出当前项目中的依赖包。

用法：uv pip freeze [OPTIONS]

 uv pip freeze
 # --------------------------
 # 输出
 # certifi==2025.4.26
 # charset-normalizer==3.4.2
 # colorama==0.4.6
 # filelock==3.18.0
 # fsspec==2025.3.2
 # huggingface-hub==0.31.1

04、uv pip list

列出当前项目环境中的依赖项，默认以表格格式输出。可以通过设置命令参数 –format json来指定以 json 格式输出。

用法：uv pip list [OPTIONS]

 uv pip list
 # --------------------------
 # 输出
 # certifi            2025.4.26
 # charset-normalizer 3.4.2
 # colorama           0.4.6
 # filelock           3.18.0
 # fsspec             2025.3.2
 # huggingface-hub    0.31.1
 
 
 uv pip list --format json
 # --------------------------
 # 输出
 # [{"name":"certifi","version":"2025.4.26"},{"name":"charset-normalizer","version":"3.4.2"},{"name":"colorama","version":"0.4.6"},{"name":"filelock","version":"3.18.0"},{"name":"fsspec","version":"2025.3.2"},{"name":"huggingface-hub","version":"0.31.1"}]

05、uv pip show

显示指定依赖的详细信息。

用法：uv pip show [OPTIONS] [PACKAGE]…

 uv pip show regex
 # --------------------------
 # 输出
 # Name: regex
 # Version: 2024.11.6
 # Location: E:codepythonMyDemo.venvLibsite-packages
 # Requires:
 # Required-by: transformers

06、uv pip tree

以树状形式展示依赖的相互关系。

用法：uv pip tree [OPTIONS]

 uv pip tree
 # --------------------------
 # 输出
 # transformers v4.51.3
 # ├── filelock v3.18.0
 # ├── huggingface-hub v0.31.1
 # │   ├── filelock v3.18.0
 # │   ├── fsspec v2025.3.2
 # │   ├── packaging v25.0
 # │   ├── pyyaml v6.0.2
 # │   ├── requests v2.32.3
 # │   │   ├── certifi v2025.4.26
 # │   │   ├── charset-normalizer v3.4.2
 # │   │   ├── idna v3.10
 # │   │   └── urllib3 v2.4.0
 # │   ├── tqdm v4.67.1
 # │   │   └── colorama v0.4.6
 # │   └── typing-extensions v4.13.2
 # ├── numpy v2.2.5

07、uv pip check

验证项目中安装包的依赖是否兼容

如果分多个步骤安装，则可以将具有冲突要求的软件包安装到环境中。

用法：uv pip check [OPTIONS]

 # 要检查环境中是否存在冲突或缺少依赖关系，请执行以下操作
 uv pip check
 # --------------------------
 # 输出
 # Checked 18 packages in 1ms
 # All installed packages are compatible

pip-tools的可替代命令

01、uv pip compile

通过 requirements.txt 文件中的依赖内容来同步环境。

同步环境时，没有在 requirements.txt文件中列出的任何包都会被删除。要保留多余的软件包，请使用 uv pip install。

假定requirements.txt’文件是通过命令 pip compile 或 uv export 输出的，那么它会包含所有可传递的依赖项。如果文件中不存在传递依赖项，则不会安装它们。可使用 –strict 对任何缺少传递依赖项发出告警。

用法：uv pip compile [OPTIONS] <SRC_FILE|–group <GROUP>>

 $ uv pip compile pyproject.toml -o requirements.txt
 $ uv pip compile requirements.in -o requirements.txt
 $ uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt
 $ uv pip compile setup.py -o requirements.txt

02、uv pip sync

根据requirements.txt文件中所列的依赖项同步到当前项目环境中。

用法：uv pip sync [OPTIONS] <SRC_FILE>…

 # 使用requirements.txt文件完成同步
 uv pip sync requirements.txt
 # 使用pyproject.toml完成同步
 uv pip sync pyproject.toml

缓存管理

01、uv cache clean

清除缓存，删除所有的条目或所有包的链接

用法：uv cache clean [OPTIONS] [PACKAGE]…

 uv cache clean

02、uv cache prune

从缓存中删除所有不可访问的对象。

用法：uv cache prune [OPTIONS]

 uv cache prune

03、uv cache dir

显示缓存目录。

默认情况下，Unix系统缓存目录为XDG_CACHE_HOME/uv 或 HOME/.cache/uv；Windows系统缓存目录为%LOCALAPPDATA%uvcache 。

当使用 –no-cache 参数时，缓存文件存储在临时目录中，并在进程退出时丢弃。另外，

可以通过cache-dir 参数指定缓存目录，或者通过 UV_CACHE_DIR环境变量来指定。

用法：uv cache dir [OPTIONS]

 uv cache dir

管理UV执行器

01、uv self update

更新uv

用法：uv self update [OPTIONS] [TARGET_VERSION]

 uv self update

02、uv version

查看uv版本

用法：uv version [OPTIONS]

 uv version 

03、uv help

查看uv使用协助

用法：uv help [OPTIONS] [COMMAND]…

 uv help

04、uv generate-shell-completion

生成 shell 补全。shell的值可能是：bash，elvish，fish，nushell，powershell，zsh。

用法：uv generate-shell-completion [OPTIONS] <SHELL>

 uv generate-shell-completion powershell

卸载UV

如果您需要从系统中移除uv，请按照以下步骤操作：

01、清理存储数据

  $ uv cache clean
  
  # windows 删除安装的内容 删除命令列出目录
  $ uv python dir && uv tool dir
  C:UsersAdministratorAppDataRoaminguvpython
  C:UsersAdministratorAppDataRoaminguv	ools
  
  # macOS / Linux 删除安装的内容
  $ rm -r "$(uv python dir)"
  $ rm -r "$(uv tool dir)"

02、删除uv和uvx二进制文件

  # macOS / Linux
  $ rm ~/.local/bin/uv ~/.local/bin/uvx
  
  # Windows
  $ rm %UserProfile%.localinuv.exe
  $ rm %UserProfile%.localinuvx.exe