VS Code + uv：建立 Python 開發環境與 `.venv` 管理流程

如果你現在還在手動裝 Python、手動建虛擬環境、再把套件一個一個補回來，uv 幾乎就是把這整串麻煩收掉。它可以幫我們管理 Python 版本、建立專案內的 .venv、維護 pyproject.toml 裡的依賴，最後再讓 VS Code 直接接上這套流程。

這篇會以 Windows 為例，但核心觀念在其他平台也一樣。請參考：uv 官方安裝文件 與 VS Code 的 Python 環境文件。前者目前仍建議從官方安裝腳本或 WinGet 安裝，後者則明確提到 VS Code 會搜尋工作區中的 .venv，也建議用 Python: Select Interpreter 來切換解譯器。把這兩件事接起來，Python 環境管理就會乾淨很多。

先建立 VS Code 工作區

VS Code 對 Python 的理解，基本上是以資料夾為單位。我們先決定一個專案資料夾，再在這個資料夾裡建立 pyproject.toml、.venv 和程式碼，整套環境就會跟著這個工作區走。

先在電腦任一位置建立一個空資料夾，例如 python-project，接著按住 Shift 對資料夾按右鍵，選擇「以 Code 開啟」。

打開後，VS Code 看到的會是一個幾乎空白的工作區。這沒有問題，因為我們就是要從這裡開始把 Python 專案建起來。

先裝好 Python 延伸模組

雖然 uv 負責的是 Python 環境，但 VS Code 要能正常辨識語法、切換解譯器、啟動偵錯，還是得先裝 Python 延伸模組。

請到左側的「延伸模組」頁面，搜尋 Python，安裝 Microsoft 提供的官方套件。

這一步做完後，VS Code 才會比較像一個完整的 Python IDE，而不是單純的文字編輯器。

安裝 uv

接下來處理 uv。依照 Astral 目前的官方文件，在 Windows 上最直接的方式是用 PowerShell 執行官方安裝腳本：

1powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

和舊文章常見的固定版本安裝網址不同，我比較建議直接用官方目前主頁上的安裝腳本，除非你真的有明確理由要鎖特定版本。

安裝完成後，uv 會放到使用者目錄下的本機路徑。新開一個終端機視窗，再輸入：

1uv --version

如果有正常印出版本號，就代表安裝完成。如果目前視窗還抓不到 uv，通常重新開一次終端機就夠了。

如果你習慣用套件管理器，官方文件目前也有提供 winget install --id=astral-sh.uv -e 的方式。不過本文先用安裝腳本繼續走下去，因為最直接。

用 uv 建立專案與 .venv

終端機打開後，先確認自己就在剛才那個工作區資料夾裡。接著可以先看 uv 目前能安裝哪些 Python 版本：

1uv python list

這裡我用 Python 3.10 當例子，因為很多既有專案到現在還停在這一支線。安裝指令如下：

1uv python install 3.10

裝好之後，開始初始化專案：

1uv init
2uv venv --python 3.10

第一行會建立基本專案骨架，包含 pyproject.toml。第二行則在目前工作區建立 .venv，而且明確指定它要用 Python 3.10。

我會建議把虛擬環境放在專案內，也就是直接用 .venv 這個名稱。原因很單純：工作區跟著專案走，VS Code 也比較容易自動找到它，搬移專案時不會把環境散落到系統其他地方。

讓 VS Code 指向專案內的 .venv

雖然 VS Code 會搜尋工作區中的 .venv，但實際開發時，我還是建議手動確認一次解譯器，不要把這件事交給運氣。

請打開 Command Palette：

1Ctrl + Shift + P

然後執行：

1Python: Select Interpreter

這時候選擇專案內 .venv\Scripts\python.exe 對應的那一個解譯器即可。

如果你看到右下角的 Python 版本已切到專案內的 .venv，後面不管是執行、型別提示，還是安裝新套件，整套環境才會真的對齊。

執行程式時，優先用 uv run

這是 uv 和一般 venv + pip 工作流很不一樣的地方。當我們用 uv run 執行程式時，uv 會依照專案設定去補足需要的環境，而不是只仰賴當前 shell 有沒有 activate 過虛擬環境。

假設你有一支 main.py，可以這樣執行：

1uv run main.py

這樣做的好處，是未來專案搬到另一台電腦時，重建流程會很一致。只要 pyproject.toml 寫得完整，uv 就知道該怎麼把環境補起來。

用 uv 管理套件，重點在 pyproject.toml

如果你以前習慣的是 pip install，那切到 uv 之後最值得調整的習慣，是把依賴管理回到專案層級，而不是只管當下環境有沒有裝成功。

安裝套件

安裝一個新套件時，直接用：

1uv add python-osc

這樣做不只是裝進 .venv，也會把依賴寫進 pyproject.toml。之後換電腦、重建環境、多人協作，這個資訊才跟得上。

刪除套件

不需要的套件，用 uv remove 拿掉：

1uv remove python-osc

它會同步更新專案設定，而不是只把環境裡的檔案刪掉。

根據 pyproject.toml 同步環境

當你手動改了 pyproject.toml，或是剛把別人的 Python 專案拉下來，最常用的就是：

1uv sync

這個指令的意思很直接：讓目前環境和專案宣告的依賴重新對齊。

從 requirements.txt 過渡到 uv

很多既有專案還是從 requirements.txt 起家，這很正常。uv 並沒有逼你一次全部改完，它目前仍支援把 requirements.txt 的套件匯入進專案設定。

如果你手上已經有一份 requirements.txt，可以用：

1uv add -r requirements.txt

這樣 uv 會讀取清單，安裝依賴，並把需要的資訊寫回專案。

如果你之後想維持專案導向的管理，就盡量讓新的依賴都走 uv add。這樣久了之後，pyproject.toml 會比到處散落的安裝紀錄好維護很多。

什麼情況下，這套流程最有感

我自己會特別推薦 uv + VS Code 的情境，大概有三種：

• 你常在不同電腦之間移動 Python 專案。
• 你不想再手動處理 Python 版本和虛擬環境。
• 你希望專案依賴能跟著程式碼走，而不是只活在某台機器裡。

像先前我整理一些需要特殊 Python 版本的專案時，最煩的通常是「環境到底怎麼重建」。uv 真正幫上的，就是這一段。

總結

uv 的價值，不只是「安裝套件比較快」。更重要的是，它把 Python 版本、.venv、依賴和執行流程收進同一套工作流裡，讓 VS Code 這種以工作區為核心的編輯器能直接接上。

如果你希望 Python 專案的環境管理乾淨一點、可重建一點，也不想再手動維護一堆分散的設定，VS Code + uv 幾乎就是現在很實用的一套基礎組合。把 .venv 放在專案內、用 uv add 管依賴、用 uv run 執行程式，後面會省很多事。

作者

Ted Liou

現職 Unity C# 工程師，主要分享 Unity、C# 與 Vibe Coding 相關技術教學。

GitHub