1. uv install

1.1 下載安裝腳本來安裝

# 用curl
curl -LsSf https://astral.sh/uv/install.sh | sh# 用wget
wget -qO- https://astral.sh/uv/install.sh | sh

1.2 使用pipx安裝uv

補充：pipx是安全地安裝和運行隔離的 Python 命令行工具，它能夠解決全局安裝python應用（ pip install --user 或 sudo pip install）的依賴沖突和環境污染問題。sudo pip install <pkg>
安裝的可執行文件位置：/usr/local/bin
安裝的庫文件位置：
/usr/local/lib/pythonX.X/dist-packages/ (Debian/Ubuntu)
/usr/lib/pythonX.X/site-packages/ (RHEL/CentOS)pip install --user <pkg>
安裝的可執行文件位置：~/.local/bin/
安裝的庫文件位置：~/.local/lib/pythonX.X/site-packages/pipx install <pkg>
將每個工具安裝在獨立的虛擬環境中
~/.local/pipx/venvs/flake8/     # flake8 的獨立環境# 先安裝pipx
sudo apt install pipx# 再安裝uv
pipx install uv
pipx ensurepath && source ~/.basrc

1.3 補充

• pipx依賴venv，需要確保venv全局安裝。sudo apt install python3.8-venv
• pip安裝提示，Not installing to existing directory。可能是之前失敗安裝存在殘留文件。pipx install --force
• 安裝uv后還需要將可執行文件目錄添加到$PATH。執行pipx ensurepath可以自動把pipx下載的工具的可執行文件目錄都添加到$PATH

2. 考慮在離線系統上安裝uv

2.1 下載并上傳安裝包

# 使用pip下載，.whl安裝包在當前目錄，可能有多個.whl文件，所以打包
pip download uv
cd .. && tar -zcvf uv.tar.gz uv/scp uv.tar.gz cg@192.168.250.234:~/Downloads/

2.2 用戶級安裝uv（~/.local/bin/）

# 解壓
cd ~/Downloads/
tar -zxvf uv.tar.gz# 安裝到用戶級site-package
pip install --no-index --find-links=~/Downloads/uv uv
--no-index：禁止從 PyPI 下載。
--find-links=.：從當前目錄查找包。# 添加~/.local/bin到$PATH
echo 'export PATH=$HOME/.local/bin:$PATH'

2.3 補充

Q：安裝包為uv-0.7.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl，包名：uv；包版本：0.7.3；python兼容版本：python3；abi標簽：none，表示不依賴python abi（不依賴任何擴展的純python包）；架構：x86_64;系統兼容性：manylinux標準（manylinux_2_17和manylinux2014）。目標機器架構為arm，無法安裝這個安裝包。
A：確認安裝包的平臺版本和目標系統平臺兼容，目標系統是x86_64的，則安裝包應該是x86_64d的， 目標系統是arm結構的，安裝包應該是arm架構的。

3. uv 管理Python解釋器

# 查看uv可安裝和已經安裝的python版本
uv list python# 安裝指定版本的python，安裝位置 /home/user01/.local/share/uv/python/
uv python install cpython-3.12# 使用已安裝的某個版本的python解釋器執行
uv run -p 3.12 main.py# 使用已安裝的某個版本的python解釋器進入交互式執行環境
uv run -p 3.12 pythonps: uv指定python解釋器版本時，如果uv沒有安裝之，則會自動安裝它

4. uv 管理依賴

# 創建工程
mkdir test && cd test
uv init -p 3.12# 目錄樹
tree
├── .git
├── .gitignore
├── .python-version  # 3.12
├── README.md
├── main.py
└── pyproject.toml  # 跟蹤項目當前依賴# 假設項目源碼文件依賴和pyproject.toml記錄的不一樣
uv sync

5. uv運行代碼

5.1 uv不在項目下執行腳本

# main.py
import requestsif __name__ == '__main__':url = 'www.baidu.com'resp = requests.get(url)print(resp.text)# 執行腳本，未導入依賴報錯
uv run main.py# 執行腳本，命令行中指定依賴，依賴下載到~/.cache/uv
uv run --no-project --with rich main..py

5.2 uv在項目下執行腳本

# 進入項目
cd test# 執行腳本，未導入依賴錯誤
uv run main.py# 執行腳本，命令行中指定依賴，依賴下載到~/.cache/uv
uv run --with requests main.py# 執行腳本，使用項目的虛擬環境維護依賴
uv add requests  # pyproject.toml記錄了requests及其依賴
uv run main.py# 打印uv工程依賴樹
uv treetest v0.1.0
└── requests v2.32.3├── certifi v2025.4.26├── charset-normalizer v3.4.2├── idna v3.10└── urllib3 v2.4.0# 從項目中以礎依賴
uv remove requests

5.3 uv執行腳本，腳本自己維護依賴

# 腳本自己加上所需依賴
uv add --script main.py requests# uv將往main.py頭插入記錄依賴信息的注釋
# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "requests",
# ]
# ///import requestsif __name__ == '__main__':url = 'https://www.baidu.com'resp = requests.get(url)print(resp.text)# 執行，以腳本模式運行，即使在uv項目中也可以不加--no-project而運行
uv run --script main.py

5.4 補充

? uv初始化項目后首次執行run會先創建項目虛擬環境：.venv
? 在uv項目中，uv run xxx.py將以項目方式運行（使用項目的虛擬環境）；在uv項目中，uv run --with xxx將使用臨時環境（~/.cache/uv/）;在項目中，uv run --script main.py將使用臨時環境（~/.cache/uv），但是腳本自己可以維護依賴，而不必在命令行中用–with來指定依賴。

6. python開發工具管理

開發需要python工具，可將這些工具添加到項目依賴，但這些工具不應該隨其他項目依賴打包。
uv add flake8 --dev

但是實際工程中，這些工具應該與項目無關，需要在其他地方維護。另外即使通過–dev可以避免項目打包時把工具打包進去，但是添加工具時可能添加工具自己的依賴到項目中而污染了項目的虛擬環境。正確做法時使用uv tool來維護這些工具。

# 工具安裝到~./cache/uv/
uv tool install flake8# 查看已經安裝的工具
uv tool list

7. 項目打包為.whl文件

# pyproject.toml文件中添加session
[project]
name = "p10-tmp"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [][prject.scripts]
test = ["test:main"]# 打包
uv build 
dist
├── p10_tmp-0.1.0-py3-none-any.whl
└── p10_tmp-0.1.0.tar.gz# 安裝離線包
uv tool install dist/p10_tmp-0.1.0-py3-none-any.whl

補充

Q&A
Q：pip如何確定package安裝到系統目錄還是用戶目錄
A：pip根據以下要素判斷該把package放到哪里：

1. 是否添加–user參數：加–user參數，package放到用戶級site-package中
2. 是否處于虛擬環境激活狀態：虛擬環境激活狀態，package放在虛擬環境的site-package中
3. 普通用戶還是特權用戶（root用戶或者sudo pip install）：普通用戶則放在用戶的site-package，特權用戶則放在系統site-package中。
   注意，普通用戶執行pip install 等價于pip install --user .

more about pip

? --user parameter
pip install --help
–user: Install to the Python user install directory for your platform. Typically ~/.local/, or %APPDATA%\Python on Windows. (See the Python documentation for site.USER_BASE for full details.)

? pip’'s doc
https://packaging.python.org/en/latest/tutorials/installing-packages/