在現代軟體開發中，特別是處理複雜的 Python 專案時，管理套件依賴是一項至關重要的任務。不同的專案可能需要不同版本的函式庫，若將所有套件都安裝在全域的 Python 環境中，極易產生版本衝突，導致難以預測的錯誤。為了解決這個問題，Python 引入了「虛擬環境」（Virtual Environment）的概念，而 `venv` 模組便是 Python 3.3 以後官方推薦的建立虛擬環境的標準工具。

什麼是 Python 虛擬環境？

簡單來說，虛擬環境是一個獨立的 Python 安裝副本，它擁有自己的 Python 解譯器、標準函式庫以及可自行安裝的第三方套件。當您在一個虛擬環境中運作時，該環境中的 `pip` 或其他套件安裝工具，只會將套件安裝到該虛擬環境的 `site-packages` 目錄下，而不會影響到全域的 Python 環境或其他虛擬環境。這就像為每個專案準備了一個專屬的「開發沙盒」，確保專案之間的依賴關係不會相互干擾。

虛擬環境的關鍵特性：

• 專案隔離： 為每個專案提供一個獨立的套件空間，避免版本衝突。
• 依賴管理： 方便管理特定專案所需的函式庫及其版本。
• 環境一致性： 確保開發、測試和生產環境的一致性，減少「在我電腦上可以跑」的問題。
• 輕量級： 相較於使用虛擬機器，虛擬環境更加輕便，佔用資源較少。

為什麼選擇 `venv`？

在 `venv` 模組出現之前，Python 社群曾廣泛使用 `virtualenv` 等第三方工具。然而，自 Python 3.3 起，`venv` 被整合進標準庫，並成為建立虛擬環境的首選方式。官方的推薦意味著 `venv` 具有良好的穩定性、跨平台相容性，並且與 Python 的核心功能緊密整合。參考 Python 3.14.0 的官方文件指出，自 3.5 版本起，`venv` 的使用已被推薦為建立虛擬環境的最佳實踐，而 `pyvenv` 這個在早期版本中使用的工具，則在 3.6 版本後被標記為棄用，並在 3.8 版本中被移除，進一步凸顯了 `venv` 的重要性。

使用 `venv` 建立虛擬環境

建立虛擬環境的過程十分直觀，只需執行一個簡單的指令。根據您的操作系統，具體命令可能略有不同。

通用命令：

在終端機或命令提示字元中，執行以下指令：

python -m venv /path/to/new/virtual/environment 

這個命令會在指定的路徑 `/path/to/new/virtual/environment` 創建一個新的虛擬環境。如果指定的目錄不存在，`venv` 會自動建立它。建立過程中，`venv` 會在該目錄下創建一個 `pyvenv.cfg` 設定檔，並包含一個 `home` 鍵，指向用於建立虛擬環境的 Python 解譯器。同時，還會創建一個 `bin` (在 Windows 上是 `Scripts`) 子目錄，其中包含一個指向基礎 Python 解譯器的複製或符號連結。

Windows 上的指令：

在 Windows 的 PowerShell 中，您可以使用：

python -m venv C:\\path\\to\ ew\\virtual\\environment 

重要提示： `venv` 模組預設會在新環境中安裝 `pip` 和 `setuptools`，方便您後續安裝其他套件。這項功能自 Python 3.4 版本起就已加入，當時也新增了 `–without-pip` 和 `–copies` 選項。

`venv` 的常用選項

執行 `python -m venv -h` 可以查看 `venv` 提供的所有可用選項。以下是一些常用且重要的選項：

• `–system-site-packages`： 啟用此選項後，虛擬環境將可以存取系統全域的 Python 套件。這在某些情況下可能有用，但通常不建議這樣做，因為這會削弱虛擬環境的隔離性。
• `–symlinks | –copies`： 控制虛擬環境如何處理 Python 解譯器。`–symlinks`（預設在許多 POSIX 系統上）會建立符號連結，而 `–copies` 則會複製整個 Python 解譯器。官方文件提醒，在 Windows 上不建議使用符號連結，因為它們的行為可能不如預期。
• `–clear`： 如果目標環境目錄已存在，此選項會先刪除其中的所有內容，然後再重新建立環境。
• `–upgrade`： 用於升級現有的虛擬環境，使其使用當前執行的 Python 版本。這在您更新了系統的 Python 版本後非常有用。
• `–without-pip`： 跳過在虛擬環境中安裝或升級 `pip`。
• `–prompt <PROMPT>`： 為虛擬環境設定一個自訂的提示符前綴。這讓您在啟用環境時，能更清楚地辨識當前所在的虛擬環境。
• `–upgrade-deps`： （自 Python 3.9 起）升級虛擬環境中的核心依賴套件（如 `pip` 和 `setuptools`）到 PyPI 上的最新版本。
• `–without-scm-ignore-files`： （自 Python 3.13 起）跳過為版本控制系統（如 Git）建立忽略檔案。預設情況下，`venv` 會為 Git 建立 `.gitignore` 檔案。

啟用與停用虛擬環境

建立虛擬環境後，您需要「啟用」它才能在其中工作。啟用過程會修改您當前終端機會話的環境變數，以便 `python` 指令指向虛擬環境中的解譯器。

啟用虛擬環境：

啟用方式取決於您的作業系統和使用的 Shell：

• POSIX (Linux/macOS):
  • Bash/Zsh: source <venv>/bin/activate
  • Fish: source <venv>/bin/activate.fish
  • Csh/Tcsh: source <venv>/bin/activate.csh
  • PowerShell (Core): <venv>/bin/Activate.ps1
• Windows:
  • cmd.exe: <venv>\Scripts\activate.bat
  • PowerShell: <venv>\Scripts\Activate.ps1

啟用後，您會注意到終端機的提示符前綴變更，顯示虛擬環境的名稱，例如 (.venv) $。

停用虛擬環境：

當您完成在虛擬環境中的工作，想要返回全域環境時，只需在終端機輸入：

deactivate 

這個指令會將環境變數恢復到啟用前的狀態。

虛擬環境的運作原理

當一個 Python 解譯器從虛擬環境運作時，`sys.prefix` 和 `sys.exec_prefix` 會指向虛擬環境的目錄，而 `sys.base_prefix` 和 `sys.base_exec_prefix` 則指向建立該環境所使用的基礎 Python 解譯器。您可以透過檢查 `sys.prefix != sys.base_prefix` 來判斷當前解譯器是否位於虛擬環境中。這是 Python 3.14.0 文件中提到的核心機制，用以區分是否處於虛擬環境內。

此外，即使沒有啟用虛擬環境，您仍然可以透過指定虛擬環境中 Python 解譯器的完整路徑來執行 Python 指令或腳本。安裝在虛擬環境中的腳本通常會包含一個 shebang 行（例如 `#!//bin/python`），使其能夠在被執行時自動使用正確的解譯器。這點在 Windows 上也得到支援，若安裝了 Python 安裝管理器，雙擊腳本檔案即可正確執行。

一次建立多個虛擬環境： `venv` 模組也支援一次性在多個指定的目錄中建立相同的虛擬環境，這對於管理擁有共享依賴的專案組合非常方便。

API 介面：自訂環境建立

對於需要更精細控制環境建立過程的開發者，`venv` 提供了 `EnvBuilder` 類別作為 API 介面。您可以繼承這個類別並覆寫其方法，以自訂環境建立的各個階段，例如：

• `ensure_directories(env_dir)`：負責建立環境目錄及其子目錄。
• `create_configuration(context)`：建立 `pyvenv.cfg` 設定檔。
• `setup_python(context)`：複製或連結 Python 解譯器。
• `setup_scripts(context)`：設置啟動腳本。
• `post_setup(context)`：在環境建立完成後的額外處理。

透過這些鉤子（hooks），開發者可以將 `venv` 整合到更複雜的自動化工作流程或自訂工具中。

最佳實踐與注意事項

• 命名慣例： 虛擬環境的目錄名稱通常是 `.venv` 或 `venv`，建議放置在專案的根目錄下。
• 版本控制： 虛擬環境目錄不應被納入版本控制系統（如 Git）。可以將其加入 `.gitignore` 檔案。
• 可拋棄性： 虛擬環境被設計為可拋棄的。如果遇到問題，最簡單的解決方案是刪除並重新建立。
• 不可移動性： 虛擬環境不應被直接移動或複製。若需要將環境移至新位置，應在其新位置重新建立，並將舊環境刪除。這是因為環境中的腳本路徑是絕對路徑，直接移動可能導致其失效。
• 依賴檔案： 使用 `pip freeze > requirements.txt` 來記錄虛擬環境中的所有套件及其版本，這對於日後重新建立環境至關重要。

正如 Python 官方文件所強調的，虛擬環境是「一次性的」，應始終有一種簡單的方法來從頭開始重建它們。依賴於 `requirements.txt` 檔案是實現這一點的最佳途徑。

結論

Python 的 `venv` 模組為開發者提供了一個強大而靈活的工具，用於建立獨立、隔離的專案開發環境。透過有效地使用虛擬環境，您可以避免套件衝突，簡化依賴管理，並確保專案在不同環境中的穩定性和一致性。從建立、啟用到停用，`venv` 的操作流程都力求簡便。理解其運作原理並遵循最佳實踐，將顯著提升您的 Python 開發效率和項目管理能力。

如果您希望深入了解 AI、創業與 Funding 的最新資訊，並與其他技術愛好者交流，我們誠摯邀請您加入我們的社群。

Source：https://docs.python.org/3/library/venv.html