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

---

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 170msBuilt 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

---

故障排除问题

故障排除指南：https://docs.astral.sh/uv/reference/troubleshooting/

---

在GitHub上打开一个issue

GitHub上的 问题跟踪器 是报告错误的理想之地
并且请求功能。确保首先搜索类似的问题，因为其他人提出类似问题的情形很常见。
可能会遇到相同的问题。

---

在 Discord 上聊天

Astral Discord : https://discord.com/invite/astral-sh

这是一个很好的地方来提问题，了解更多关于UV的信息，并与社区其他成员互动。

2025年1月27日

---

集成指南

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

了解如何将 uv 集成到其他软件中：

• 在 Docker 镜像中使用
• 与 Jupyter 一起使用
• 与 pre-commit 一起使用
• 在 GitHub Actions 中使用
• 在 GitLab CI/CD 中使用
• 与替代包索引一起使用
• 安装 PyTorch
• 构建 FastAPI 应用程序
• 与 AWS Lambda 一起使用

或者，探索 概念文档 以获取每个功能的全面概述。

2025年1月7日

---

伊织 2025-03-24（一）