安裝

方法一：使用安裝腳本

#?macOS 和 Linux
curl -LsSf https://astral.sh/uv/install.sh | sh#?Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

方法二：使用包管理器

#?macOS (Homebrew)
brew install uv#?Windows (Scoop)
scoop install uv#?通過 pip 安裝
pip install uv

入門

使用虛擬環境

1. 創建虛擬環境

#?創建一個新的虛擬環境
uv venv myproject#?創建指定 Python 版本的虛擬環境
uv venv --python 3.11 myproject#?激活虛擬環境
#?Linux/macOS:
source myproject/bin/activate
#?Windows:
myproject\Scripts\activate

2.安裝包

#?安裝單個包
uv pip install requests#?安裝多個包
uv pip install requests numpy pandas#?安裝指定版本的包
uv pip install "django>=4.0,<5.0"#?從 requirements.txt 安裝
uv pip install -r requirements.txt

使用uv方式

1.項目初始化

#?初始化一個新項目
uv init my_uv_test
cd my_uv_test

#?查看項目結構
tree ..
├── main.py
├── pyproject.toml
└── README.md1 directory, 3 files

使用 pyproject.toml 管理依賴

[project]
name =?"my-uv-test"
version =?"0.1.0"
description =?"Add your description here"
readme =?"README.md"
requires-python =?">=3.12"
dependencies = []

3. 依賴管理

安裝依賴

#?安裝項目依賴（從 pyproject.toml）
uv pip install -e .#?安裝開發依賴
uv pip install -e ".[dev]"#?安裝所有可選依賴
uv pip install -e ".[dev,docs,web]"#?生成鎖定文件
uv pip freeze > requirements.lock#?同步依賴（確保環境與 requirements.txt 完全一致）
uv pip sync requirements.txt

添加依賴

#?添加生產依賴
uv add requests
uv add "django>=4.0,<5.0"
uv add requests beautifulsoup4 pandas#?添加開發依賴
uv add --dev pytest black flake8
uv add --dev "pytest>=7.0"#?添加可選依賴組
uv add --group docs sphinx sphinx-rtd-theme
uv add --group web fastapi uvicorn

添加依賴后再次查看pyproject.toml

[project]
name =?"my-uv-test"
version =?"0.1.0"
description =?"Add your description here"
readme =?"README.md"
requires-python =?">=3.12"
dependencies = ["requests>=2.32.3",
]

運行

uv run 選擇 Python 版本的優先級順序：

1. 明確指定版本（最高優先級）

uv run --python 3.11 script.py
uv run --python python3.12 script.py
uv run --python /usr/bin/python3.10 script.py

2. 項目配置文件

如果有?pyproject.toml：

[project]
requires-python?=?">=3.9"

或者?.python-version?文件：

3.11.5

3. 環境變量

export?UV_PYTHON=3.11
uv run script.py

4. 系統默認 Python

如果以上都沒有，uv 會按順序查找：

• python3
• python
• 系統 PATH 中的第一個可用 Python

建議：?在項目中明確指定 Python 版本，避免環境差異導致的問題

使用 uv 一句話運行 Python 文件

uv run script.py

在沒有?pyproject.toml?的情況下，uv 有幾種方式來處理依賴：

1. 使用 `--with` 參數臨時安裝包

uv run --with requests --with pandas script.py

2. 通過腳本內聯聲明依賴（PEP 723）

在 Python 腳本頂部添加特殊注釋：

# /// script
# dependencies = [
# ? "requests",
# ? "pandas>=1.0",
# ]
# ///import?requests
import?pandas?as?pd# 你的代碼...

然后直接運行：

uv run script.py

3. 使用 requirements.txt

如果目錄下有?requirements.txt，uv 會自動讀取：

uv run script.py

4. 完全不管理依賴

如果沒有以上任何配置，uv run?會：

• 創建一個臨時的虛擬環境
• 只安裝 Python 標準庫

• 如果腳本導入了第三方包但沒有聲明依賴，會報?ImportError
  推薦做法：?使用 PEP 723 的內聯依賴聲明，這樣腳本是自包含的，任何人都能直接用?uv run script.py?運行。

uv的優缺點

這是一份很好的 uv 使用指南！我來補充一下 uv 的優缺點分析：

uv 的優缺點

優點 ?

1.?極快的速度

• 用 Rust 編寫，比 pip 快 10-100 倍
• 并行下載和安裝包
• 智能緩存機制

2.?統一的工具鏈

# 一個工具搞定所有事情
uv venv ? ? ? ?# 創建虛擬環境
uv pip install?# 包管理
uv run ? ? ? ??# 運行腳本
uv add ? ? ? ??# 添加依賴

3.?現代化的依賴管理

• 支持?pyproject.toml

• 自動生成鎖定文件
• 依賴組管理（dev, docs, test 等）

4.?開箱即用

# 無需預先創建虛擬環境
uv run --with requests script.py

5.?PEP 723 支持

# /// script
# dependencies = ["requests"]
# ///
import?requests

6.?跨平臺一致性

• Windows、macOS、Linux 行為一致
• 統一的安裝方式

缺點 ??

1.?生態系統兼容性

• 某些包的構建可能有問題
• 復雜的 C 擴展包支持不完善
• 企業環境的私有源配置較復雜

2.?學習成本

• 新的命令和概念
• 與傳統 pip/virtualenv 工作流不同
• 團隊需要統一工具

3.?相對年輕

• 社區相對較小
• 文檔和教程不如 pip 豐富
• 可能存在未發現的 bug

4.?依賴 Rust 生態

• 某些平臺可能缺少預編譯二進制
• 從源碼編譯需要 Rust 工具鏈

適用場景

? 推薦使用

• 新項目開發
• 對速度有要求的 CI/CD
• 現代 Python 開發工作流
• 個人項目和學習

? 謹慎使用

• 傳統企業環境
• 復雜的遺留項目
• 需要特殊包構建的項目
• 團隊對新工具抗拒

總結

uv 是 Python 包管理的未來趨勢，特別適合追求效率的現代開發者。雖然還有一些兼容性問題，但其速度和易用性優勢明顯，值得在新項目中嘗試使用。