uv - Getting Started 开始使用 [官方文档翻译]

编程乐园

已于 2025-03-25 17:38:05 修改

阅读量1.5k

点赞数 32

分类专栏： # Python 文章标签： uv python 包管理 pip pypi

于 2025-03-24 10:55:02 首次发布

本文链接：https://blog.csdn.net/lovechris00/article/details/146470399

版权

Python 专栏收录该内容

134 篇文章

订阅专栏

uv

https://docs.astral.sh/uv/

一个极快的Python包和项目管理器，用Rust编写。

亮点

❇️ 运行脚本，支持内联依赖元数据
🐍 安装和管理 Python 版本。
🛠️ 运行和安装以 Python 包形式发布的工具。
🔩 包含一个用于性能提升的 pip 兼容接口熟悉 CLI。
🏢 支持Cargo风格的工作区，适用于可扩展的项目。
💾 磁盘空间高效，拥有用于依赖去重的一个全局缓存。
⏬ 无需 Rust 或 Python，通过 curl 或 pip 可安装。
🖥️ 支持 macOS、Linux 和 Windows。

uv由Astral支持，它是的创造者 Ruff

安装

安装 uv 使用我们的官方独立安装程序：
macOS 和 Linux

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

Windows

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

然后，查看第一步或者继续阅读以获取简要概述。

提示：uv 也可以通过 pip、Homebrew 等方式进行安装。在安装页面查看所有方法。

项目

uv 管理项目依赖和环境，支持锁文件、工作区等功能。类似于 rye 或 poetry：

$ uv init example
Initialized project `example` at `/home/user/example`

$ cd example

$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
   Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
 + example==0.1.0 (from file:///home/user/example)
 + ruff==0.5.4

$ uv run ruff check
All checks passed!

$ uv lock
Resolved 2 packages in 0.33ms

$ uv sync
Resolved 2 packages in 0.70ms
Audited 1 package in 0.02ms

查看项目指南以开始使用。
uv 也支持构建和发布项目，即使它们不是用 uv 管理的。查看打包指南。

脚本

uv 管理单文件脚本的依赖和环境。
创建一个新的脚本并添加声明其依赖项的内置元数据：

$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py

$ uv add --script example.py requests
Updated `example.py`

然后，在隔离的虚拟环境中运行脚本：

$ uv run example.py
Reading inline script metadata from: example.py
Installed 5 packages in 12ms
<Response [200]>

查看脚本指南以开始使用。

工具

uv执行并安装由Python包提供的命令行工具，类似于pipx。
在临时环境中运行一个工具使用 uvx（uv tool run 的别名）:

$ uvx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
 + pycowsay==0.0.0.2
  """

  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)_______
       (__)\       )\/\
 ||----w |
 || ||

使用 uv tool install 安装一个工具：

$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
 + ruff==0.5.4
Installed 1 executable: ruff

$ ruff --version
ruff 0.5.4

查看工具指南以开始使用。

Python 版本

uv 安装 Python 并允许快速切换版本。
安装多个 Python 版本：

$ uv python install 3.10 3.11 3.12
Searching for Python versions matching: Python 3.10
Searching for Python versions matching: Python 3.11
Searching for Python versions matching: Python 3.12
Installed 3 versions in 3.42s
 + cpython-3.10.14-macos-aarch64-none
 + cpython-3.11.9-macos-aarch64-none
 + cpython-3.12.4-macos-aarch64-none

下载所需的 Python 版本：

$ uv venv --python 3.12.0
Using CPython 3.12.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

$ uv run --python [[email protected]](/cdn-cgi/l/email-protection) -- python
Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>>

使用当前目录中的特定 Python 版本：

$ uv python pin 3.11
Pinned `.python-version` to `3.11`

查看安装 Python 指南以开始安装。

pip 接口

uv 提供了 pip、pip-tools 和 virtualenv 常用命令的即插即用替代方案。
uv 通过高级特性扩展了它们的接口，例如依赖版本覆盖。
平台无关的解决方案、可重复的解决方案、替代解决方案策略以及更多。
迁移到uv而不改变您现有的工作流程——并体验10-100倍的速度提升——使用 uv pip 接口。

编译平台无关的需求文件：

$ uv pip compile docs/requirements.in \
   --universal \
   --output-file docs/requirements.txt
Resolved 43 packages in 12ms

创建一个虚拟环境：

$ uv venv
Using CPython 3.12.3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

安装已锁定的依赖项：

$ uv pip sync docs/requirements.txt
Resolved 43 packages in 11ms
Installed 43 packages in 208ms
 + babel==2.15.0
 + black==24.4.2
 + certifi==2024.7.4
 ...

查看pip接口文档以开始使用。

了解更多

查看第一步或直接跳转到指南

2025年2月10日

入门

为了帮助您开始使用 uv，我们将涵盖几个重要主题：

安装 uv
安装后的第一步
uv的特點概览
如何获得帮助

继续阅读，或跳转到另一个部分：

快速开始，使用指南进行常见工作流程。
了解uv的核心概念的更多信息。
使用参考文档来查找关于特定事物的详细信息。

2024年8月16日

安装 uv

安装方法

安装 uv，可以使用我们提供的独立安装程序或您选择的包管理器。

独立安装程序

uv提供了一个独立的安装程序，用于下载和安装uv：
macOS 和 Linux
使用 curl 下载脚本并使用 sh 执行它：

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

如果您的系统没有 curl，您可以使用 wget：

$ wget -qO- https://astral.sh/uv/install.sh |.sh

请求特定版本，通过将其包含在URL中：

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

Windows

使用 irm 下载脚本，并用 iex 执行它：

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

更改执行策略允许从互联网运行脚本。
请求特定版本，通过将其包含在URL中：

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

提示：在使用之前，可以检查安装脚本：
macOS 和 Linux

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

Windows

$ powershell -c "irm https://astral.sh/uv/install.ps1 | more"

或者，可以从 GitHub 直接下载安装程序或二进制文件。

查看安装器配置文档以获取详细信息。
自定义您的 UV 安装。

PyPI

为了方便，uv 发布到了 PyPI。
如果从 PyPI 安装，我们建议将 uv 安装到一个隔离环境中，例如，使用 pipx：

$ pipx install uv

然而，pip 也可以被使用：

$ pip install uv

注意： uv ships 为许多平台配备了预构建的分布（轮子）；如果给定平台没有轮子，则将从源代码构建uv，这需要Rust工具链。请参阅贡献设置指南了解从源头构建紫外线的详细信息。

Cargo

uv可通过Cargo获取，但必须从Git构建，而不是通过crates.io。
关于其依赖未发布crate的情况。

$ cargo install --git https://github.com/astral-sh/uv uv

Homebrew

uv 可在核心 Homebrew 软件包中找到。

$ brew install uv

WinGet

uv可通过WinGet获取。

$ winget install --id=astral-sh.uv  -e

Scoop

uv 可通过 Scoop 获取。

$ scoop install main/uv

Docker

uv提供了一款Docker镜像：ghcr.io/astral-sh/uv
查看我们关于在Docker中使用uv的指南以获取更多详细信息。

GitHub 发布

uv 发布的工件可以直接从 GitHub 发布
每个发布页面都包括所有支持平台上的二进制文件以及使用说明。
使用 github.com 而不是 astral.sh 的独立安装程序。

升级 uv

当通过独立安装程序安装 uv 时，它可以根据需要自行更新：

uv self update

提示：更新uv将重新运行安装程序并可能修改您的shell配置文件。要禁用此行为，设置INSTALLER_NO_MODIFY_PATH=1。

当使用另一种安装方法时，自动更新被禁用。使用包管理器进行更新升级方法来替代。例如，使用 pip：

$ pip install --upgrade uv

Shell 自动补全

提示：您可以通过运行 echo $SHELL 来帮助您确定您的 shell。
要启用 uv 命令的 shell 自动补全，运行以下命令之一：

Bash

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

zsh

echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

fish

echo 'uv generate-shell-completion fish | source' >> ~/.config/fish/config.f.sh

Elvish

echo 'eval (uv generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv

PowerShell / pwsh

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

要启用 uvx 的 shell 自动补全，运行以下命令之一：
Bash

echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc

zsh

echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc

fish

echo 'uvx --generate-shell-completion fish | source' >> ~/.config/fish/config.f.sh

Elvish

echo 'eval (uvx --generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv

PowerShell / pwsh

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

然后重新启动 shell 或源 shell 配置文件。

卸载

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

1、清理存储数据（可选）：

$ uv cache clean
$ rm -r "$(uv python dir)"
$ rm -r "$(uv tool dir)"

提示：在删除二进制文件之前，您可能想删除 uv 存储的任何数据。

2、删除 uv 和 uvx 二进制文件：
macOS 和 Linux

$ rm ~/.local/bin/uv ~/.local/bin/uvx

Windows

$ rm $HOME.local\bin\uv.exe
$ rm $HOME.local\bin\uvx.exe

注意：在0.5.0之前，uv被安装到了~/.cargo/bin。可以从那里删除这些二进制文件。
uninstall. 升级到旧版本将不会自动删除二进制文件 ~/.cargo/bin.

2025年2月24日

第一次使用 uv

在安装 uv 之后，您可以通过运行 uv 来检查 uv 是否可用。
命令：

$ uv
An extremely fast Python package manager.

Usage: uv [OPTIONS] <COMMAND>

...

您应该会看到一个列出可用命令的帮助菜单。

2024年9月3日

特性

uv 提供了 Python 开发所需的基本功能——从安装 Python 到对简单功能进行修改
脚本用于在支持多个 Python 版本和平台的庞大项目中工作。
uv的接口可以分为几个部分，这些部分可以独立使用或一起使用。

Python 版本

安装和管理 Python 本身。

uv python install: 安装 Python 版本。
uv python list: 查看可用的 Python 版本。
uv python find: 查找已安装的 Python 版本。
uv python pin: 将当前项目固定使用特定的 Python 版本。
uv python uninstall: 卸载一个 Python 版本。

请参阅 guide on installing Python 以开始学习。

脚本

执行独立的 Python 脚本，例如，example.py。

uv run: 运行一个脚本。
uv add --script: 将依赖项添加到脚本中
uv remove --script: 从脚本中删除一个依赖项

查看运行脚本的指南以开始使用。

项目

创建和开发 Python 项目，即使用一个 pyproject.toml。

uv init: 创建一个新的 Python 项目。
uv add: 添加项目依赖。
uv remove: 从项目中移除一个依赖。
uv sync: 将项目的依赖与环境同步。
uv lock: 创建项目依赖的锁文件。
uv run: 在项目环境中运行一个命令。
uv tree: 查看项目的依赖树。
uv build: 将项目构建为分发存档。
uv publish: 将项目发布到包索引中。

查看项目指南以开始。

工具

运行和安装发布到 Python 包索引中的工具，例如 ruff 或 black。

uvx / uv tool run：在一个临时环境中运行一个工具。
uv tool install: 在全局范围内安装一个工具。
uv 工具卸载: 卸载一个工具。
uv 工具列表: 列出已安装的工具.
uv tool update-shell: 更新 shell 以包括工具可执行文件。

查看工具指南以开始使用。

pip 接口

手动管理环境和包 — 旨在用于遗留工作流程或情况中
高级命令提供不了足够控制。
创建虚拟环境（替代 venv 和 virtualenv）:

uv venv: 创建一个新的虚拟环境。

查看使用环境的文档以获取详细信息。

在环境中管理包（替代 pip 和 pipdeptree )

uv pip install: 将包安装到当前环境。
uv pip show: 显示已安装软件包的详细信息。
uv pip freeze: 列出已安装的包及其版本。
uv pip check: 检查当前环境是否有兼容的包。
uv pip list: 列出已安装的包。
uv pip uninstall: 卸载包。
uv pip tree: 查看环境的依赖树。

查看管理包的文档以获取详细信息。
在环境中锁定包（替换 pip-tools）:

uv pip compile: 将需求编译进锁定文件。
uv pip sync: 将环境与锁文件同步。

查看关于锁定环境的文档以获取详细信息。

重要：这些命令并不完全实现它们所基于的工具的接口和行为。你离通用工作流程越远，遇到差异的可能性就越大。有关详细信息，请参阅pip 兼容性指南。

实用工具

管理并检查 uv 的状态，例如缓存、存储目录，或执行自更新操作：

uv cache clean: 清除缓存条目。
uv cache prune: 删除过时的缓存条目。
uv cache dir: 显示 uv 缓存目录路径。
uv tool dir: 显示 uv 工具目录路径。
uv python dir: 显示安装的 uv Python 版本的路径。
uv self update: 更新 uv 到最新版本。

2025年2月5日

获取帮助

帮助菜单

--help 标志可用于查看命令的帮助菜单，例如，对于 uv：

uv --help

要查看特定命令的帮助菜单，例如，对于 uv init：

uv init --help

当使用 --help 标志时，uv 显示一个简化的帮助菜单。要查看更长的帮助菜单，请
命令，使用 uv help：

uv help

要查看特定命令的完整帮助菜单，例如，对于 uv init：

uv help init

使用长帮助菜单时，uv 将尝试使用 less 或 more 来“分页”输出，以便它更易于阅读。
不一次性显示所有内容。要退出分页器，按 q。

查看版本

在寻求帮助时，确定您所使用的 uv 版本非常重要——有时需要知道您正在使用的版本才能提供有效的帮助。
有时候问题在更新的版本中已经被解决。
要检查已安装的版本：

uv version

以下也是有效的：

$ uv --version      # Same output as `uv version`
$ uv -V             # Will not include the build commit and date
$ uv pip --version  # Can be used with a subcommand