uv簡介

uv 是由 Astral 公司開發，用 Rust 編寫的快速 Python 包管理器。
它最初作為 pip 工作流的替代品推出，如今已擴展成為一個端到端的解決方案，能夠管理 Python 項目、命令行工具、單文件腳本，甚至 Python 本身。
uv 類似于 Python 版本的 Cargo，為開發者提供一個快速、可靠、易用的統一接口。

主要特性如下：

1. 端到端項目管理
   通過 uv run、uv lock 和 uv sync 等命令，uv 可以基于標準元數據生成跨平臺的鎖文件并安裝依賴。
   相比 Poetry、PDM 和 Rye 等工具，uv 在性能上更具優勢。

2. 工具管理
   使用 uv tool install 和 uv tool run（別名 uvx），可以在隔離的虛擬環境中安裝和運行命令行工具。
   支持執行一次性命令，無需顯式安裝，速度比 pipx 更快。

3. Python 安裝
   通過 uv python install 可以自動下載安裝 Python，類似 pyenv，但效率更高。

4. 單文件腳本支持
   支持基于 PEP 723 的內聯元數據，只需使用 uv run 即可執行獨立的 Python 腳本。

這些功能建立在 uv 高性能的跨平臺依賴解析器之上。無論是處理小型腳本還是大型項目，uv 都能提供良好的性能和可靠性，適合從初學者到專家的各種 Python 開發需求。

亮點

官方文檔：https://docs.astral.sh/uv/

• 🚀 一個工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等多個工具
• ?? 比 pip 快 10 到 100 倍
• 🗂? 提供全面的項目管理功能，支持通用鎖文件
• ?? 支持運行腳本，并支持內聯依賴元數據
• 🐍 可安裝并管理多個 Python 版本
• 🛠? 支持運行和安裝以 Python 包發布的工具
• 🔩 提供兼容 pip 的接口，在保留熟悉 CLI 的同時獲得性能提升
• 🏢 支持類 Cargo 的工作區，用于構建可擴展項目
• 💾 節省磁盤空間，依賴去重采用全局緩存
• ? 可通過 curl 或 pip 安裝，無需預裝 Rust 或 Python
• 🖥? 支持 macOS、Linux 和 Windows
• uv 由 Ruff 的開發者 Astral 團隊支持

與 pip、pip-tools、pipx、poetry、pyenv、virtualenv 對比

📦 pip

簡介：pip 是 Python 官方推薦的包管理器，由 Python Packaging Authority（PyPA）維護。(PyPI)

功能：

• 安裝和卸載 Python 包
• 支持從 PyPI、Git 倉庫、本地目錄等多種來源安裝(GitHub)

優點：

• 廣泛使用，社區支持良好
• 簡單易用，適合初學者(PyPI)

缺點：

• 不支持依賴鎖定，可能導致環境不一致
• 缺乏虛擬環境和項目管理功能

適用場景：

• 快速安裝單個包
• 與其他工具（如 virtualenv、pip-tools）結合使用(GitHub)

---

🔧 pip-tools

簡介：pip-tools 是由 Jazzband 社區維護的工具集，旨在增強 pip 的功能。

功能：

• pip-compile：從 requirements.in 生成鎖定的 requirements.txt
• pip-sync：根據 requirements.txt 安裝或卸載依賴(Poetry)

優點：

• 確保項目依賴的一致性
• 與 pip 兼容，易于集成

缺點：

• 依賴解析速度較慢
• 功能相對單一，僅處理依賴鎖定

適用場景：

• 需要嚴格依賴鎖定的項目
• 與 pip 和 virtualenv 結合使用

---

🛠? pipx

簡介：pipx 是由 PyPA 維護的工具，專注于在隔離的環境中安裝和運行 Python 命令行應用。

功能：

• 在隔離的虛擬環境中安裝 CLI 工具
• 運行一次性命令

優點：

• 避免全局污染，隔離性好
• 便于管理和運行 CLI 工具

缺點：

• 安裝和運行速度較慢
• 功能專注于 CLI 工具管理，范圍有限

適用場景：

• 需要在隔離環境中運行 CLI 工具
• 避免全局安裝帶來的依賴沖突

---

📦 poetry

簡介：Poetry 是由 Python 社區開發的項目管理工具，旨在簡化依賴管理和打包發布流程。

功能：

• 使用 pyproject.toml 管理項目依賴
• 自動創建和管理虛擬環境
• 構建和發布 Python 包

優點：

• 一體化管理項目生命周期
• 使用 pyproject.toml，符合 PEP 518 標準

缺點：

• 依賴解析速度較慢
• 對 Python 版本管理支持有限

適用場景：

• 需要完整項目管理的開發者
• 希望簡化構建和發布流程

---

🐍 pyenv

簡介：pyenv 是由社區開發的工具，用于安裝和管理多個 Python 版本。

功能：

• 安裝和切換多個 Python 版本
• 支持全局和本地（每個項目）版本設置

優點：

• 支持多個 Python 版本的切換
• 適用于開發和測試不同版本的兼容性

缺點：

• 安裝新版本需編譯，耗時較長
• 不支持 Windows 系統

適用場景：

• 需要管理多個 Python 版本的開發者
• 測試不同 Python 版本的兼容性

---

🧪 virtualenv

簡介：virtualenv 是由社區開發的工具，用于創建隔離的 Python 虛擬環境。

功能：

• 創建隔離的虛擬環境
• 支持不同項目使用不同的依賴

優點：

• 輕量級，創建環境速度快
• 適用于簡單的項目隔離

缺點：

• 不包含依賴管理功能
• 需手動管理依賴

適用場景：

• 需要簡單環境隔離的項目
• 與 pip 或 pip-tools 結合使用

---

? uv

簡介：uv 是由 Astral 公司開發的高性能 Python 包和項目管理器，使用 Rust 編寫，旨在替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多個工具。

功能：

• 安裝和管理 Python 包
• 創建和管理虛擬環境
• 安裝和管理 Python 版本
• 運行和安裝 CLI 工具
• 支持單文件腳本的依賴管理
• 提供與 pip 兼容的接口

優點：

• 安裝速度快，性能優越
• 集成依賴管理、虛擬環境、Python 版本管理等功能
• 支持跨平臺，兼容 macOS、Linux 和 Windows

缺點：

• 作為新興工具，生態尚在發展中

適用場景：

• 需要高性能依賴解析和安裝的項目
• 希望統一管理項目依賴、虛擬環境和 Python 版本
• 需要在隔離環境中運行 CLI 工具

功能/工具	pip	pip-tools	pipx	poetry	pyenv	virtualenv	uv
包安裝	?	?	?	?	?	?	?
依賴鎖定	?	?	?	?	?	?	?
虛擬環境管理	?	?	?	?	?	?	?
Python 版本管理	?	?	?	?	?	?	?
CLI 工具管理	?	?	?	?	?	?	?
構建與發布	?	?	?	?	?	?	?
安裝速度	中	慢	慢	中	慢	快	快
跨平臺支持	?	?	?	?	?	?	?

安裝uv

uv 可以通過多種方式進行安裝，以下是一些常見的安裝方式：

1. 使用官方獨立安裝器：

• macOS / Linux：

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

• Windows：

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

2. 通過 PyPI 安裝：

• 使用 pip：

  pip install uv
  

• 或使用 pipx：

  pipx install uv
  

安裝方式若使用獨立安裝器，可通過以下命令自更新至最新版：

uv self update

安裝之后，可以通過uv help命令檢查是否安裝成功：

快速開始

uv 提供了 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 版本

---

📄 腳本執行（Scripts）

用于執行獨立的 Python 腳本，如 example.py：

• uv run：運行腳本
• uv add --script：為腳本添加依賴
• uv remove --script：為腳本移除依賴

---

🧰 項目管理（Projects）

用于創建和維護包含 pyproject.toml 的 Python 項目：

• uv init：創建新項目
• uv add：添加項目依賴
• uv remove：移除項目依賴
• uv sync：將項目依賴同步到虛擬環境中
• uv lock：生成項目依賴的鎖文件
• uv run：在項目環境中運行命令
• uv tree：查看依賴樹
• uv build：構建項目為可發布包
• uv publish：將項目發布到 PyPI 等package index

---

🛠? 工具管理（Tools）

用于運行和安裝發布到 Python package indexes 的命令行工具（如 ruff 或 black）：

• uvx / uv tool run：在臨時環境中運行工具
• uv tool install：安裝工具到用戶級環境
• uv tool uninstall：卸載工具
• uv tool list：列出已安裝的工具
• 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：將 requirements 編譯為鎖文件
• uv pip sync：使用鎖文件同步環境

---

🧹 實用命令（Utility）

用于管理 uv 的狀態，如緩存、存儲路徑或自我更新等：

• uv cache clean：清理緩存條目
• uv cache prune：清理過期緩存條目
• uv cache dir：顯示 uv 緩存目錄
• uv tool dir：顯示工具安裝目錄
• uv python dir：顯示已安裝的 Python 版本路徑
• uv self update：將 uv 更新到最新版本

uv安裝python

如果你的系統中已經安裝了 Python，uv 會自動檢測并使用它，無需額外配置。不過，uv 也可以安裝和管理 Python 版本。uv 會根據需要自動安裝缺失的 Python 版本。

如果要安裝最新版本的 Python：

uv python install

Python 并未發布官方的可分發二進制文件。因此，uv 使用了來自 Astral 的 python-build-standalone 項目的分發版。且，當 Python 通過 uv 安裝時，它不會在全局環境中可用（即不能通過 python 命令直接調用）。

安裝特定版本的 Python：

uv python install 3.12

要安裝多個 Python 版本：

uv python install 3.11 3.12

要安裝其他方的Python實現，例如 PyPy：

uv python install pypy@3.10

要重新安裝 uv 管理的 Python 版本，請使用 --reinstall 選項，例如：

uv python install --reinstall

這將重新安裝所有之前安裝的 Python 版本。隨著 Python 分發版的不斷改進，重新安裝可能會解決一些 bugs，即使 Python 版本未發生變化。

查看已安裝的 Python 版本：

uv python list

使用 uv 時，Python 不需要顯式安裝。默認情況下，uv 會在需要時自動下載缺失的 Python 版本。例如，以下命令會在未安裝 Python 3.12 時自動下載它：

uvx python@3.12 -c "print('hello world')"

即使未指定具體的 Python 版本，uv 也會按需下載最新版本。例如，如果系統中沒有 Python 版本，以下命令將會在創建新虛擬環境之前先安裝 Python：

uv venv

如果您的系統中已有 Python 安裝，uv 會使用現有的 Python 安裝。

uv運行腳本

Python 腳本是用于獨立執行的文件，例如使用 python <script>.py。使用 uv 運行腳本可以確保依賴項被妥善管理，而無需手動管理虛擬環境。

運行無依賴的腳本

如果腳本沒有依賴項，可以使用以下方式運行：

example.py

print("Hello world")

運行：

uv run example.py

如果僅使用標準庫模塊，也無需額外操作：

import os
print(os.path.expanduser("~"))

uv run example.py

腳本也可以接收命令行參數：

example.py

import sys
print(" ".join(sys.argv[1:]))

uv run example.py test
uv run example.py hello world!

還可以通過標準輸入傳入腳本：

echo 'print("hello world!")' | uv run -

或者使用 shell 的 here-document：

uv run - <<EOF
print("hello world!")
EOF

如果是在帶有 pyproject.toml 的項目目錄中使用 uv run，它會先安裝當前項目依賴。若腳本與項目無關，可以加 --no-project 跳過：

uv run --no-project example.py

運行有依賴的腳本

如果腳本依賴于第三方庫，它們需要被安裝到腳本運行的環境中。uv 推薦按需創建環境，而不是維護一個長期存在的虛擬環境。這需要你顯式聲明依賴項。

例如，以下腳本依賴 rich：

import time
from rich.progress import trackfor i in track(range(20), description="For example:"):time.sleep(0.05)

如果沒有指定依賴，會運行失敗：

uv run --no-project example.py

使用 --with 添加依賴：

uv run --with rich example.py

指定版本范圍：

uv run --with 'rich>12,<13' example.py

重復使用 --with 可添加多個依賴。若在項目中運行，這些依賴會與項目依賴合并，如不想這樣處理，可使用 --no-project。

創建帶元數據的 Python 腳本

Python 近期新增了 內聯腳本元數據 的標準格式，可用來選擇 Python 版本和聲明依賴。用以下命令初始化腳本：

uv init --script example.py --python 3.12

添加依賴：

uv add --script example.py 'requests<3' 'rich'

腳本頂部會增加如下聲明：

# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

示例：

import requests
from rich.pretty import pprintresp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

執行：

uv run example.py

?? 重要提示
使用內聯元數據時，即使在項目中運行 uv run，也會忽略項目依賴，無需加 --no-project。

聲明 Python 版本：

# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///
type Point = tuple[float, float]
print(Point)

📌 dependencies 字段必須存在，即使為空。

如果所需版本未安裝，uv 會自動下載。

使用 shebang 創建可執行文件

可在腳本開頭添加 shebang，使其無需 uv run 直接執行：

#!/usr/bin/env -S uv run --scriptprint("Hello, world!")

賦予執行權限：

chmod +x greet
./greet

也支持聲明依賴：

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///
import httpx
print(httpx.get("https://example.com"))

使用其他package indexes

你可以通過 --index 指定依賴的包索引：

uv add --index "https://example.com/simple" --script example.py 'requests<3' 'rich'

這將在元數據中加入：

# [[tool.uv.index]]
# url = "https://example.com/simple"

鎖定依賴

對于帶 PEP 723 元數據的腳本，可以使用 uv lock 鎖定依賴：

uv lock --script example.py

將創建 example.py.lock 文件。后續命令如 uv run --script 等將復用鎖定版本。

提高可復現性

你可以在元數據中添加 exclude-newer 限制依賴的發布時間：

# /// script
# dependencies = [
#   "requests",
# ]
# [tool.uv]
# exclude-newer = "2023-10-16T00:00:00Z"
# ///

指定不同的 Python 版本

每次運行腳本時可指定不同的 Python 版本：

import sys
print(".".join(map(str, sys.version_info[:3])))

運行：

uv run example.py
uv run --python 3.10 example.py

運行 GUI 腳本

在 Windows 上，.pyw 腳本會通過 pythonw 運行：

from tkinter import Tk, ttkroot = Tk()
root.title("uv")
frm = ttk.Frame(root, padding=10)
frm.grid()
ttk.Label(frm, text="Hello World").grid(column=0, row=0)
root.mainloop()

帶依賴的 GUI 示例：

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QGridLayoutapp = QApplication(sys.argv)
widget = QWidget()
grid = QGridLayout()label = QLabel("Hello World!")
grid.addWidget(label)widget.setLayout(grid)
widget.setGeometry(100, 100, 200, 50)
widget.setWindowTitle("uv")
widget.show()
sys.exit(app.exec_())

uv運行工具

許多 Python 包會提供可用作工具的應用程序。uv 對此提供了專門支持，使得調用和安裝這些工具更加便捷。

運行工具

uvx 命令可以調用工具，而無需先安裝它。

例如，要運行 ruff：

uvx ruff

💡 注意
這實際上等價于：

uv tool run ruff

uvx 是為了方便而提供的別名。

你可以在工具名稱后添加參數：

uvx pycowsay hello from uv

使用 uvx 運行工具時，會將其安裝在臨時的、隔離的環境中。

💡 注意
如果你在一個項目中運行工具，而該工具要求你的項目已安裝（例如使用 pytest 或 mypy），請使用 uv run 而非 uvx。否則，該工具會在一個與項目隔離的虛擬環境中運行。
如果你的項目是扁平結構（例如未使用 src 目錄），那么項目無需安裝，uvx 就可以正常使用。在這種情況下，只有當你希望將工具版本固定在項目依賴中時，uv run 才更有意義。

包名與命令名不同的情況

當你運行 uvx ruff 時，uv 實際安裝的是 ruff 包，該包提供了 ruff 命令。但有時包名和命令名不同。

你可以使用 --from 參數指定包名，例如：

uvx --from httpie http

指定版本運行工具

你可以使用 命令@<版本> 的形式運行特定版本的工具：

uvx ruff@0.3.0 check

運行最新版本：

uvx ruff@latest check

--from 同樣支持版本指定：

uvx --from 'ruff==0.3.0' ruff check

或指定版本范圍：

uvx --from 'ruff>0.2.0,<0.3.0' ruff check

?? 注意：@ 語法只支持精確版本。

請求 extras（附加功能）

使用 --from 可以帶上 extras：

uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

結合版本也可以：

uvx --from 'mypy[faster-cache,reports]==1.13.0' mypy --xml-report mypy_report

請求不同來源

--from 還支持從其他來源安裝工具。

例如，從 Git 倉庫：

uvx --from git+https://github.com/httpie/cli httpie

指定分支：

uvx --from git+https://github.com/httpie/cli@master httpie

指定 tag：

uvx --from git+https://github.com/httpie/cli@3.2.4 httpie

指定 commit：

uvx --from git+https://github.com/httpie/cli@2843b87 httpie

使用插件的命令

你也可以添加額外依賴，例如在運行 mkdocs 時附帶 mkdocs-material：

uvx --with mkdocs-material mkdocs --help

安裝工具

如果某個工具經常使用，可以將其安裝到持久環境中，并加入 PATH，而不是每次都用 uvx 調用。

💡 提示
uvx 是 uv tool run 的別名。其它涉及工具的命令則需要完整的 uv tool 前綴。

安裝 ruff：

uv tool install ruff

安裝后，其可執行文件會放在 PATH 中的一個 bin 目錄里，可以直接運行：

ruff --version

?? 注意：
安裝工具不會使其模塊在當前環境中可導入。以下命令會失敗：

python -c "import ruff"

這種隔離有助于減少工具、腳本和項目依賴之間的沖突。

與 uvx 不同，uv tool install 操作的是包，會安裝該包提供的所有可執行文件。

例如：

uv tool install httpie

會安裝 http, https, httpie 等命令。

也可以帶版本約束：

uv tool install 'httpie>0.1.0'

也支持從源安裝：

uv tool install git+https://github.com/httpie/cli

支持附帶額外包：

uv tool install mkdocs --with mkdocs-material

Ruff：極速的Python代碼檢查工具

這是一個由Rust編寫的Python代碼檢查和格式化工具，致力于比現有的工具（如Flake8、Black）快10到100倍，并且集成了更多功能。無論你是Python開發者，還是開源項目的維護者，Ruff都能帶給你驚人的提升。

Ruff 是一個極快的 Python 代碼檢查器和格式化工具，使用 Rust 語言編寫，具備以下亮點：

• ?? 極速性能：速度比現有工具（如 Flake8 和 Black）快 10 到 100 倍；
• 🐍 安裝便捷：可通過 pip 安裝，簡單方便；
• 🛠? 支持配置：兼容 pyproject.toml 配置文件；
• 🤝 兼容性強：完全支持 Python 3.13；
• ?? 功能全面：對等支持 Flake8、isort 和 Black 的功能；
• 📦 內置緩存：智能緩存機制，避免重復分析未修改的文件；
• 🔧 自動修復：具備自動修復能力，如刪除未使用導入等；
• 📏 規則豐富：內置 800+ 條規則，支持常用 Flake8 插件（如 flake8-bugbear）；
• ?? 編輯器集成：官方提供 VS Code 等主流編輯器插件；
• 🌎 Monorepo 友好：支持層次化和級聯配置，適配大型項目結構。

Ruff 的目標是在性能上遙遙領先的同時，提供統一、強大且現代化的工具體驗。它不僅能夠取代 Flake8（及其多個插件）、Black、isort 等工具，而且可以以數十倍甚至上百倍的速度完成相同任務。

主要特點

• 🚀 極速性能：Ruff 的執行速度遠超其他工具，甚至比 Pylint 快上 1000 倍。例如，在 Dagster（一個包含 25 萬行代碼的模塊）上，Ruff 的運行時間僅為 0.4 秒，而 Pylint 則需要 約 2.5 分鐘。
• 🌐 廣泛的社區支持：Ruff 已被多個知名開源項目采用，如 Apache Airflow、FastAPI、Pandas、SciPy 等。
• ?? 簡潔配置：支持通過 pyproject.toml、ruff.toml 或 .ruff.toml 文件進行配置，默認配置已涵蓋絕大多數常見錯誤。

Ruff 的安裝與使用

• 使用 pip 安裝：

  pip install ruff
  

• 使用 pipx 安裝：

  pipx install ruff
  

• 使用 uv 工具安裝：

  uv tool install ruff@latest   # 全局安裝
  uv add --dev ruff             # 添加到項目中
  

• 使用安裝腳本（適用于 macOS 和 Linux）：

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

• Windows PowerShell 安裝：

  powershell -c "irm https://astral.sh/ruff/install.ps1 | iex"
  

Ruff 的核心功能

• 🔍 代碼檢查（Linting）：查找代碼中的潛在錯誤并給出修復建議：

  ruff check
  

• 🎨 代碼格式化（Formatting）：自動格式化代碼，符合 PEP 8 等規范：

  ruff format
  

• 🛠? 自動修復：自動修復常見錯誤（如未使用的導入）：

  ruff check --fix
  

• 🧩 集成支持：支持 VS Code 插件，也可用作 GitHub Action 實現自動化工作流。

Ruff 支持 800+ 條規則，涵蓋多個流行 Python 工具的功能，例如：

• ? 自動修復：如刪除未使用的導入（類似 autoflake）；

• 🔒 安全檢查：如檢測潛在安全風險（基于 flake8-bandit）；

• 📈 代碼優化：增強類型檢查、API 使用建議等；

• 📋 代碼質量檢查：

  • flake8-bugbear
  • flake8-commas
  • flake8-docstrings
  • flake8-import-conventions
  • flake8-logging
  • 等等

升級工具

升級工具使用：

uv tool upgrade ruff

如果之前安裝時使用了版本范圍（如 ruff >=0.3,<0.4），則升級會遵循該范圍。

若想替換約束，可重新安裝：

uv tool install ruff>=0.4

升級所有已安裝工具：

uv tool upgrade --all

指定 Python 版本

默認情況下，uv 會使用系統默認的 Python 解釋器。

你可以使用 --python 顯式指定：

運行工具時：

uvx --python 3.10 ruff

安裝工具時：

uv tool install --python 3.10 ruff

升級工具時：

uv tool upgrade --python 3.10 ruff

uv項目管理

uv 支持管理基于 pyproject.toml 的 Python 項目依賴。

你可以使用 uv init 命令創建一個新的 Python 項目：

uv init hello-world
cd hello-world

或者，在當前工作目錄中初始化項目：

mkdir hello-world
cd hello-world
uv init

uv 會創建以下文件結構：

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

其中，main.py 包含一個簡單的 “Hello world” 程序。你可以通過以下命令運行它：

uv run main.py

項目結構說明

一個項目由多個關鍵部分組成，uv 會在首次運行如 uv run、uv sync 或 uv lock 等命令時創建虛擬環境和 uv.lock 文件。

完整的結構如下所示：

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

pyproject.toml

該文件包含項目的元數據：

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

你可以在這個文件中指定依賴項，也可以配置描述、許可證等項目信息。它可以手動編輯，也可以通過命令行使用 uv add 和 uv remove 來管理依賴。

此外，也可以通過 [tool.uv] 部分在該文件中設置 uv 的配置選項。

.python-version

該文件指定項目默認使用的 Python 版本，uv 會據此創建虛擬環境。

.venv

這是項目的虛擬環境目錄，uv 會將所有依賴安裝在此處，確保項目與系統環境隔離。

uv.lock

這是跨平臺的鎖文件，記錄項目的精確依賴版本，用于確保在不同機器上可重復、可一致地安裝環境。
與 pyproject.toml（描述依賴要求）不同，uv.lock 中存儲的是實際安裝的解析版本。

注意：該文件是可讀的 TOML 文件，但應由 uv 自動維護，不建議手動編輯。

依賴管理

使用 uv add 添加依賴項（會同步更新鎖文件和虛擬環境）：

uv add requests

你也可以添加特定版本或指定源碼地址：

uv add 'requests==2.31.0'
uv add git+https://github.com/psf/requests

從 requirements.txt 遷移時，可以使用 -r 參數：

uv add -r requirements.txt -c constraints.txt

移除依賴包：

uv remove requests

升級某個依賴包：

uv lock --upgrade-package requests

該命令將嘗試將指定包更新為最新兼容版本，同時保持其他依賴不變。

運行命令

uv run 可在項目虛擬環境中執行任意腳本或命令。

每次運行前，uv 會自動驗證 lockfile 是否與 pyproject.toml 同步，并保持環境一致，無需手動干預，確保你始終運行在一致的鎖定環境中。

例如，使用 flask：

uv add flask
uv run -- flask run -p 3000

運行腳本：

# example.py
import flask
print("hello world")

uv run example.py

也可以手動同步環境并激活虛擬環境后再運行命令：

macOS / Linuxuv sync
source .venv/bin/activate
flask run -p 3000
python example.pyWindowsuv sync
.venv\Scripts\activate
flask run -p 3000
python example.py

注意：若未使用 uv run，必須先激活虛擬環境，不同操作系統和 shell 的激活方式不同。

構建發行包

使用 uv build 可構建源碼包和 wheel 包，構建產物將默認保存在 dist/ 目錄：

uv build
ls dist/

uv構建和發布包

uv 支持通過 uv build 將 Python 項目打包為源碼分發包（source distribution）和二進制分發包（wheel），并通過 uv publish 上傳到包注冊中心（如 PyPI）。

在發布項目之前，你需要確保項目已經準備好進行分發打包。

如果你的 pyproject.toml 中沒有定義 [build-system]，那么 uv 默認不會為你構建項目。這通常意味著項目尚未準備好進行分發。

注意：

如果你有不希望發布的內部包，可以將其標記為私有：

[project]
classifiers = ["Private :: Do Not Upload"]

該設置會讓 PyPI 拒絕你上傳的包，但不會影響其他注冊中心的安全或隱私設置。

官方還建議使用每個項目專屬的 token。沒有匹配該項目的 PyPI token，包就不會被意外發布。

構建你的包

使用以下命令構建包：

uv build

默認情況下，uv build 會構建當前目錄下的項目，并將構建產物放入 dist/ 子目錄中。

你也可以指定目錄或包進行構建：

uv build <SRC>                 # 構建指定目錄下的包
uv build --package <PACKAGE>  # 構建當前工作區中的指定包

提示：
默認情況下，uv build 會在解析構建依賴時使用 pyproject.toml 中 [tool.uv.sources] 的配置項。
為了確保在禁用 tool.uv.sources（如使用 pypa/build 等其他構建工具）時依然能正確構建包，建議發布前使用：

uv build --no-sources

發布你的包

使用以下命令將包發布到注冊中心：

uv publish

你可以通過命令行或環境變量設置發布憑證：

• 使用 --token 或 UV_PUBLISH_TOKEN
• 或使用 --username / UV_PUBLISH_USERNAME 和 --password / UV_PUBLISH_PASSWORD

如果你從 GitHub Actions 發布到 PyPI，則無需設置憑證，只需將其添加為 受信任的發布者 即可。

注意：

PyPI 現在不再支持使用用戶名和密碼發布包，你必須使用 token。使用 token 相當于設置：

--username __token__
--password <your-token>

如果你使用自定義的索引地址（例如 TestPyPI），需在 pyproject.toml 中添加如下配置，并使用 --index 指定：

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

例如：

uv publish --index testpypi

注意：

使用 uv publish --index <name> 時必須存在 pyproject.toml 文件，也就是說 CI 中發布任務必須包含項目代碼 checkout 步驟。

雖然 uv publish 會自動重試失敗的上傳，但發布過程中可能仍會出現部分文件已上傳、部分失敗的情況。

對于 PyPI，你可以直接重復執行相同命令，重復文件會被忽略。
對于 其他注冊中心，使用 --check-url <index url> 指定檢查 URL（即索引地址而非發布地址）。uv 會跳過重復上傳并能處理并發上傳時的沖突。

注意：檢查時，已上傳文件必須與之前完全一致，否則會報錯（避免同版本包的源碼與 wheel 不一致）。

安裝測試

可以使用以下命令測試包是否能被成功安裝和導入：

uv run --with <PACKAGE> --no-project -- python -c "import <PACKAGE>"

--no-project 標志可避免從當前目錄中安裝本地項目。

提示：

如果你剛剛安裝了該包，為了避免使用緩存版本，可添加：

--refresh-package <PACKAGE>

總結

uv 的設計初衷是為了解決傳統 Python 包管理工具在性能和功能整合方面的不足。它特別適用于以下場景：(CSDN博客)

1. 大型項目或團隊協作：在需要管理復雜依賴關系和多個開發環境的項目中，uv 的統一管理和快速安裝特性可以顯著提高效率。(CSDN博客)

2. 頻繁構建和部署的項目：對于需要頻繁構建和部署的項目，uv 的快速依賴解析和安裝能力可以節省大量時間。(CSDN博客)

3. 需要嚴格依賴鎖定的項目：uv 提供了跨平臺的鎖定文件（uv.lock），確保在不同環境中安裝一致的依賴版本，提升項目的可重復性和穩定性。(CSDN博客)

4. 希望簡化工具鏈的開發者：uv 集成了 pip、virtualenv、pip-tools 等工具的功能，減少了工具之間的切換，提高了開發效率。

盡管 uv 在性能和功能整合方面表現出色，但對于追求開發自由度的個人開發者來說，可能會感受到以下限制：

• 自動化程度高：uv 自動管理虛擬環境和依賴，可能會讓習慣手動配置的開發者感到不適應。

• 依賴 pyproject.toml：uv 主要依賴 pyproject.toml 進行配置，對于習慣使用 requirements.txt 的開發者來說，可能需要調整使用習慣。

• 學習成本：雖然 uv 兼容 pip 的命令，但要充分利用其全部功能，仍需花時間學習其新的命令和工作流程。

綜上，對于uv的強大我是持肯定態度的，他提供了比pip更快速的包安裝和包管理，提供了比venv，venvwrapper等更方便的虛擬環境管理，更將pip-tools、pipx、poetry、pyenv、virtualenv這些亂七八糟的工具統一化！

uv的確是個好工具，但對于項目構建，我目前還是習慣freeze一個requirement.txt然后在Dockerfile里面寫：

RUN pip install -r requirement.txtCMD ["python","main.py"]

然后使用helm去部署我的大型服務。其次對于腳本文件執行，能用python script.py為什么還要使用uv run script.py，uv是一個輔助工具并不是一個rust寫的python解釋器。

個人還是傾向于自由化的開發…^_^