uv - Getting Started 開始使用 [官方文檔翻譯]

文章目錄

uv
- 亮點
- 安裝
- 項目
- 腳本
- 工具
- Python 版本
- pip 接口
- 了解更多
入門
安裝 uv
- 安裝方法
- - 獨立安裝程序
  - PyPI
  - Cargo
  - Homebrew
  - WinGet
  - Scoop
  - Docker
  - GitHub 發布
- 升級 uv
- Shell 自動補全
- 卸載
第一次使用 uv
特性
- Python 版本
- 腳本
- 項目
- 工具
- pip 接口
- 實用工具
獲取幫助
- 幫助菜單
- 查看版本
- 故障排除問題
- 在GitHub上打開一個issue
- 在 Discord 上聊天
集成指南

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