uv - 開啟 Python 專案最好的方式

Python 由於其語法簡潔易讀好上手，因此經常用於數據分析以及機器學習領域。然而其版本間相容性問題及套件管理依賴問題經常造成開發者的困擾。 當前有許多工具試圖解決這些問題，例如 pipenv、poetry、conda 等等，而 uv 則是其中我認為最好的選擇。

uv 是一款用 Rust 語言開發的 Python 套件管理及專案管理工具。Rust 由於其接近於 C/C++ 的高效能特性，使得 uv 也同樣具備高效能及低資源消耗的優點。

此外，uv 不僅只專注於版本管理或是套件管理，而是希望打造全方位的 Python 解決方案，讓開發者能夠專注於程式碼的撰寫，而不需要花費過多時間在環境配置及相依性管理上。另外 uv 還能夠跨平台使用，因此不論在 Windows、macOS 或是 Linux 上都能有同樣的開發習慣。

安裝 uv

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" 一行指令就能完成安裝。

安裝 Python

uv 安裝 Python 也非常簡單，只需要使用 uv python install <version> 即可，例如 uv python install 3.10。如果沒有指定版本，uv 會自動安裝最新的穩定版本。

使用 uv python list 可以查看可以安裝及已經安裝的 Python 版本，加上 --only-installed 參數則可以只顯示已安裝的版本。

建立專案

可以使用 uv init <project-name> 來建立一個新的專案，這個指令會自動建立一個新的資料夾並且初始化 uv 專案結構：

uv init my_project
cd my_project

或者也可以在現有的資料夾中使用 uv init 來初始化專案：

mkdir my_project
cd my_project
uv init

uv 會自動建立如下結構的專案：

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

想在創建專案時同時指定 Python 版本，可以使用 --python <version> 參數，例如 uv init my_project --python 3.10。 如果指定的版本尚未安裝，uv 會自動幫你安裝。

管理套件

uv 使用 pyproject.toml 來管理專案的相依性套件，比起使用 pip 及 requirements.txt，這種方式能夠更好的解決套件版本衝突的問題。

安裝套件只需要使用 uv add <package> 指令，例如：

uv add requests

安裝特定版本的套件，可以使用 == 來指定版本號，例如：

uv add 'requests==2.28.1'

移除套件則使用 uv remove <package>，例如：

uv remove requests

如果要從 requirements.txt 安裝套件，可以使用 uv add -r requirements.txt。

執行專案

專案依照上述方式配置好後，可以使用 uv run <script> 來執行專案，例如：

uv run main.py

虛擬環境

如果你只是想要快速的運行或是測試某個 Python 版本以及套件，可以使用 uv venv --python <version> 在當前路徑下建立一個臨時且隔離的虛擬環境，例如：

uv venv --python 3.10
source .venv/bin/activate

使用 uv pip install <package> 或是 uv pip uninstall <package> 來安裝/移除套件，這些套件只會安裝在這個虛擬環境中，不會影響到全域的 Python 環境。

接著使用 uv run <script> 來執行 Python 腳本，例如：

uv run main.py

要退出虛擬環境，只需要使用 deactivate 指令即可。並且將 .venv 刪除後，這個虛擬環境就會完全被移除。

從 pip 遷移到 uv

如果你已經有一個使用 pip 及 requirements.txt 的專案，可以使用 uv add -r requirements.txt 來將相依性套件匯入到 uv 專案中，這個指令會自動解析 requirements.txt 並且將套件及其版本寫入到 pyproject.toml 中。

cd existing_project
uv init
uv add -r requirements.txt
uv sync
uv run main.py # 測試程式碼是否能正常運行

uv sync 是在確保專案的虛擬環境已安裝所有必要依賴，並與其鎖定檔案 uv.lock 保持最新與一致

以上是我認為新手開啟 Python 專案最好的方式，一般情況下新手往往會直接從官方網站下載 Python，然後使用 pip 來安裝套件，這樣雖然能夠快速上手，但卻容易在專案中遇到版本衝突或是相依性問題。並且隨著接觸的專案越來越多元後，終究還是得花時間來整理這些環境配置問題。因此從一開始就使用 uv 來建立版本及套件管理，對於長期在 Python 生態系中的人來說，會是更好的選擇。

參考資料

• uv 官方文件
• uv GitHub 倉庫
• 一次搞定 Python 版本管理/套件安裝/虛擬環境的極速神器 - uv