常用操作指令

初始化新專案

1
2
3
4


uv init my-project
uv python pin 3.12 # 固定虛擬環境Python版本
uv init my-project --python 3.12 # 前面兩個指令合併成一條
cd my-project

產生的專案目錄結構為

1
2
3
4
5
6


   my-project/
├── .python-version  # 指定此專案使用的 Python 版本
├── pyproject.toml    # 專案設定檔與套件依賴清單
├── README.md
├── main.py           # 入口預設檔案
└── .gitignore

提示：如果你已經在現有的目錄中，直接執行 uv init 即可

建立與管理虛擬環境 uv 會在安裝套件或執行程式時自動建立並維護 .venv，但也可以手動掌控：
- 自動建立環境：只需直接新增套件或執行程式，uv 會自動在根目錄建立 .venv。
- 手動指定 Python 版本建立環境：
安裝與管理套件在 uv 專案模式下，建議使用 uv add 與 uv remove 來管理相依套件，這會同步更新 pyproject.toml 與 lockfile（uv.lock）

1
2
3
4
5
6


# 安裝一般套件
uv add requests
# 安裝開發用套件（Dev dependencies）
uv add --dev pytest ruff
# 移除套件
uv remove requests

同步/安裝所有專案依賴 如果剛從 Git 下載現有專案，直接執行uv sync 這會根據 uv.lock 精確地還原與安裝所有指定的套件至 .venv 中

執行程式與工具不需要手動執行 source .venv/bin/activate，使用 uv run 就會自動在專案的虛擬環境中執行指令

1

uv run main.py

1

uv lock

作用：uv 會重新檢查 pyproject.toml 的變更，並將最新、最相容的套件版本寫入 uv.lock。
驗證方式：執行後若 uv.lock 沒有任何檔案變更（git status 顯示乾淨），代表兩者原本就是一致的；如果有變更，請將更新後的 uv.lock 一併提交。

重建開發環境

1
2


uv sync
uv sync --locked

--locked 參數：會強制檢查 pyproject.toml 與 uv.lock 是否完全一致。如果不一致，uv 會直接報錯拒絕執行，這能幫你提早發現「改了 pyproject.toml 卻忘了更新 uv.lock`」的問題

`.gitignore`內容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# --------------------------------------------------
# uv / Python 虛擬環境 (絕對不要 commit)
# --------------------------------------------------
.venv/

# --------------------------------------------------
# Python 編譯快取與暫存檔 (建議加入)
# --------------------------------------------------
__pycache__/
*.py[cod]
*$py.class

# --------------------------------------------------
# uv 臨時快取 (通常 uv 快取在全域，但若設定在專案內需排除)
# --------------------------------------------------
.uv/

常用指令速查表

操作	指令
初始化專案	`uv init <project-name>`
安裝套件	`uv add <package>`
安裝開發套件	`uv add --dev <package>`
移除套件	`uv remove <package>`
同步鎖定檔並安裝	`uv sync`
在虛擬環境執行	`uv run <command/script>`
升級所有套件	`uv lock --upgrade`

常用操作指令

.gitignore內容

常用指令速查表

`.gitignore`內容