Python uv 快速上手：建立第一個專案

這篇用最短路徑，幫你完成一個能跑的 Python 專案——建立你在 uv 的第一個可用環境。就像養第一隻小水獺：先讓牠能吃能睡，進階撸水獺技巧之後再說。

前置條件

• 已安裝 uv（見 總覽 的安裝指令）
• 終端機能執行 uv 指令

最小範例：建立第一支專案

步驟 1：驗證 uv 已安裝

uv --version

有版本號就代表裝好了。沒有？回去跑安裝腳本，然後重開 terminal。

步驟 2：初始化專案

uv init my-app
cd my-app

uv 會自動建立 pyproject.toml、.python-version、main.py、README.md。結構大概長這樣：

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

步驟 3：執行預設程式

uv run main.py

會看到 Hello from my-app!——恭喜，第一個專案誕生。

步驟 4：加依賴並執行

uv add requests

接著改一下 main.py，加幾行試試：

import requests
r = requests.get("https://httpbin.org/get")
print(r.status_code)

再執行：

uv run main.py

看到 200 就代表依賴有正確裝進虛擬環境——不用手動 pip install，也不用 source .venv/bin/activate，這種無腦感就是 uv 的快樂泉源。

常見問題排查

下一步

專案能跑之後，建議先搞懂 pyproject.toml 跟 uv.lock 在幹嘛，下一篇會講這些核心概念：
👉 核心概念