Python 版本管理完全指南｜詳解 pyenv、venv、Anaconda 的使用方法

By 佐川 直弘 | Naohiro Sagawa (運営者)

※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。

1. 前言

Python 是一種深受歡迎的程式語言，廣泛用於從初學者到專業開發者。然而，由於 Python 的版本更新頻繁，許多使用者在維護開發環境或在不同專案之間管理版本時，會面臨各種挑戰。

本篇文章將深入說明 Python 版本管理的重要性及其實作方法。我們將介紹如何選擇合適的版本管理工具，以及這些工具的具體使用方式。若您希望高效運用 Python，這將是不可錯過的實用指南！

1-1. 為什麼需要管理 Python 的版本？

為了理解 Python 版本管理的重要性，我們來看看幾種常見的情境。

1-1-1. 每個專案可能需要不同的 Python 版本

在企業系統開發或個人專案中，基於所使用的函式庫或框架的需求，可能會需要指定版本的 Python。例如：

• Django 2.2 支援 Python 3.5～3.8
• TensorFlow 1.x 支援 Python 2.7 或 3.5
• TensorFlow 2.x 需要 Python 3.6 以上

由此可見，不同工具對應的建議 Python 版本各不相同。如果沒有妥善管理環境，可能會導致函式庫無法正常運作。

1-1-2. 直接修改系統內建的 Python 可能導致系統錯誤

Windows、macOS 或 Linux 系統通常會預先安裝 Python，尤其是 Linux，其作業系統部分功能依賴 Python。如果不小心更改了系統內建的 Python 版本，可能會導致系統發生無法預期的錯誤。

若未透過版本管理工具而直接覆蓋安裝 Python，有可能會影響整個作業系統的穩定性，因此必須謹慎管理。

1-1-3. 統一開發環境有助於團隊協作

在團隊開發中，讓所有成員在相同的開發環境下工作是很重要的。如果每個人使用不同的 Python 版本，可能會產生執行差異，進而導致 bug。

善用版本管理工具，可以讓團隊成員使用一致的環境，提升協作效率與開發品質。

1-2. Python 版本管理的方法

管理 Python 版本有多種方式，以下是幾個常見的工具。

1-2-1. pyenv

「pyenv」是最廣泛使用的 Python 版本管理工具，可輕鬆切換不同版本的 Python，不會影響系統預設的 Python，並可同時管理多個版本。

1-2-2. venv

venv 是 Python 標準函式庫中提供的虛擬環境工具，可以為每個專案建立獨立環境。雖不直接管理 Python 版本，但非常適合建立依賴特定版本的專案環境。

1-2-3. Anaconda

Anaconda 是為資料科學與機器學習開發所設計的 Python 發行版本，透過其套件管理系統「conda」來進行 Python 版本與套件的管理。

1-2-4. asdf

asdf 是一款多語言版本管理工具，除了 Python，也支援 Node.js、Ruby 等多種語言。它可以依專案切換版本，方便維持開發環境的一致性。

1-3. 小結

Python 的版本管理與開發效率及系統穩定性息息相關。對於同時處理多個專案的開發者，或想嘗試不同版本的使用者，選擇合適的工具來管理環境是不可或缺的。

下一節將詳細介紹如何確認當前安裝的 Python 版本，協助您為版本管理做好準備。

2. 如何確認 Python 的版本

在開始進行 Python 的版本管理之前，了解目前所使用的 Python 版本是非常重要的。如果不清楚當前環境的版本，可能會導致在非預期的環境下執行程式，進而引發問題。

本章將介紹如何在 Windows、macOS、Linux 等不同作業系統上確認 Python 的版本。

2-1. 在 Windows 上確認 Python 版本的方法

在 Windows 環境中，可以透過命令提示字元（cmd）或 PowerShell 來檢查 Python 的版本。

2-1-1. 使用命令提示字元確認版本

1. 按下 [Win] 鍵 + [R] 鍵，輸入「cmd」並開啟命令提示字元。
2. 輸入以下指令，並按下 Enter 鍵：

python --version

或是：

python -V

3. 螢幕上會顯示當前的 Python 版本。

Python 3.10.4

2-1-2. 使用 PowerShell 確認版本

透過 PowerShell 檢查版本的方法基本與 cmd 相同：

1. 開啟開始選單，搜尋「PowerShell」 並啟動。
2. 輸入以下指令並按下 Enter：

python --version

3. 會顯示當前的 Python 版本。

注意事項：

• 根據安裝位置不同，可能需要使用 python3 指令而非 python。
• 如果出現「指令無法識別」的情況，請確認環境變數是否正確設置。

2-2. 在 macOS 上確認 Python 版本的方法

macOS 通常預先安裝 Python，可以透過終端機來確認版本。

2-2-1. 使用終端機確認版本

1. 按下 [Command] + [Space]，輸入「Terminal」並開啟終端機。
2. 輸入以下指令：

python3 --version

或是：

python3 -V

3. 會顯示 Python 的版本資訊。

Python 3.9.7

2-2-2. 注意 Python2 和 Python3 的差異

在 macOS 中，python 指令有時會對應到 Python 2.x。若要使用 Python 3，建議使用 python3 指令。

python --version  # 可能顯示 Python 2.x
python3 --version  # 顯示 Python 3.x 的版本

注意事項：

• 在 macOS Big Sur 之後的版本，預設傾向使用 Python 3.x，Python 2.x 已被淘汰。

2-3. 在 Linux 上確認 Python 版本的方法

大多數 Linux 發行版（如 Ubuntu、Debian、CentOS、Fedora）都內建安裝了 Python，可以透過終端機確認版本。

2-3-1. 使用終端機確認版本

1. 打開終端機，輸入以下指令：

python3 --version

或是：

python3 -V

2. 會顯示如下結果：

Python 3.8.10

2-3-2. 確認是否仍安裝了 Python 2

某些較舊的系統可能仍有 Python 2.x，可使用以下指令確認：

python --version

如果顯示 Python 2.x.x，代表系統預設仍是使用 Python 2。

2-3-3. 系統中尚未安裝 Python 的情況

如果執行 python3 --version 時出現「Command ‘python3’ not found」等錯誤，表示尚未安裝 Python。可使用以下指令進行安裝：

Ubuntu/Debian 系：

sudo apt update
sudo apt install python3

CentOS/RHEL 系：

sudo yum install python3

Fedora：

sudo dnf install python3

2-4. 小結

不同作業系統有不同的方式來確認 Python 的版本，但大多數情況下可透過 python --version 或 python3 --version 指令完成。

• Windows → 使用 cmd 或 PowerShell 輸入 python --version
• macOS → 終端機中輸入 python3 --version
• Linux → 終端機中輸入 python3 --version，如仍有 Python 2，也可使用 python --version

為了後續順利管理版本，請先確認您目前的環境。下一章節將說明如何選擇合適的 Python 版本管理工具及其特點。

3. 如何選擇適合的 Python 版本管理工具

為了有效管理不同版本的 Python，使用專門的工具是最有效率的方法。然而，市面上有許多版本管理工具可供選擇，初學者往往會感到困惑。

本章將介紹幾款常見的 Python 版本管理工具，並說明各自的特色與適用場景，幫助你找到最適合自己的工具。

3-1. 常見的 Python 版本管理工具

以下是幾種常見的 Python 版本管理工具：

每種工具都有其優點與限制，根據用途選擇最合適的工具是關鍵。

3-2. pyenv（最適合版本管理）

3-2-1. 什麼是 pyenv？

pyenv 是一款可以讓你在不同 Python 版本之間快速切換的工具。
當你在不同專案中需要不同版本的 Python 時，它會非常實用。

3-2-2. pyenv 的優點

• 可同時安裝並共存多個 Python 版本
• 不會影響系統預設的 Python
• 只需一行指令即可切換版本
• 支援 Windows、macOS、Linux

3-2-3. 推薦給這樣的使用者：

• 不同專案需要使用不同版本的 Python
• 希望快速切換 Python 版本
• 不想更動系統的 Python 環境

3-3. venv（適合需要虛擬環境的使用者）

3-3-1. 什麼是 venv？

venv 是 Python 內建的虛擬環境建立工具。它的重點不在於版本管理，而是幫助你為每個專案建立獨立的執行環境。

3-3-2. venv 的優點

• Python 內建，無需額外安裝
• 每個虛擬環境可安裝不同套件
• 可分離每個專案的依賴

3-3-3. 推薦給這樣的使用者：

• 希望每個專案有自己的函式庫環境
• 不想安裝額外工具，只用 Python 原生功能
• 想專注於虛擬環境的管理

3-4. Anaconda（資料科學／機器學習專用）

3-4-1. 什麼是 Anaconda？

Anaconda 是專為資料分析與機器學習開發打造的 Python 發行版本，透過內建的 conda 工具來管理 Python 與套件。

3-4-2. Anaconda 的優點

• 內建常用資料科學套件（如 numpy、pandas、scikit-learn）
• 與 Jupyter Notebook 高度整合
• 使用 conda 命令管理套件與版本簡單易懂

3-4-3. 推薦給這樣的使用者：

• 從事機器學習或資料分析
• 經常使用 Jupyter Notebook
• 想快速建構適用於數據處理的開發環境

3-5. asdf（多語言版本管理工具）

3-5-1. 什麼是 asdf？

asdf 是一款可以統一管理多種程式語言（如 Python、Node.js、Ruby、Go 等）版本的工具。

3-5-2. asdf 的優點

• 可集中管理多種程式語言
• 每個專案都可設定專屬版本
• 不影響系統環境即可切換語言版本

3-5-3. 推薦給這樣的使用者：

• 除了 Python，也使用其他語言開發
• 想要彈性切換專案所需的語言版本
• 希望集中管理所有開發工具的版本

3-6. 如何選擇最適合的工具？

根據你的使用目的，可以依照以下準則選擇：

3-7. 小結

每種 Python 版本管理工具都有不同的特性與優勢。你應根據使用目的與開發需求，來選擇最適合的工具。

• 一般用途／版本切換 → pyenv
• 建立簡單虛擬環境 → venv
• 資料分析與機器學習 → Anaconda
• 同時管理多種語言 → asdf

下一章節將深入探討「虛擬環境的活用」，讓你學會如何為不同專案建立獨立的執行環境。

4. 善用虛擬環境（Virtual Environment）

為了妥善進行 Python 的版本與套件管理，虛擬環境（Virtual Environment） 是不可或缺的工具。透過虛擬環境，可以為每個專案建立獨立的開發環境，並讓不同版本的套件或 Python 共存。

本章將介紹虛擬環境的基本概念，並詳細說明如何使用主要工具（venv 與 Poetry）來建立與管理虛擬環境。

4-1. 什麼是虛擬環境？

虛擬環境是一種機制，讓你能夠在每個專案中使用獨立的 Python 執行環境。
一般情況下，Python 套件是安裝在全系統中；但透過虛擬環境，你可以：

4-1-1. 使用虛擬環境的優點

• 防止不同專案間的套件衝突
• 例如：A 專案使用 Django 3.2，B 專案使用 Django 4.0，可以同時存在而互不干擾。
• 保持系統的 Python 環境乾淨
• 不會影響系統層級的 Python，減少系統錯誤風險。
• 便於團隊開發時統一環境
• 透過共享 requirements.txt 或 pyproject.toml，團隊可快速建立一致的環境。

4-2. 使用 venv 建立虛擬環境

Python 原生提供 venv 工具來建立虛擬環境，不需額外安裝即可使用。

4-2-1. 建立虛擬環境的方法

1. 建立專案資料夾

mkdir my_project
cd my_project

2. 建立虛擬環境

python3 -m venv venv

這裡的 venv 是資料夾名稱，也可以自定義。

4-2-2. 啟用虛擬環境

啟用後，你所安裝的 Python 套件只會作用在此環境中。

Windows：

venv\Scripts\activate

macOS/Linux：

source venv/bin/activate

啟用後，提示字元會顯示 (venv)：

(venv) user@hostname:~/my_project$

4-2-3. 停用虛擬環境

當你完成開發時，可使用以下指令離開虛擬環境：

deactivate

4-2-4. 刪除虛擬環境

只需刪除該資料夾即可：

macOS/Linux：

rm -rf venv

Windows：

rd /s /q venv

4-3. 使用 Poetry 進行虛擬環境與依賴管理

除了 venv，你也可以使用 Poetry 這個工具，它提供更完整的專案與套件管理功能。

4-3-1. 什麼是 Poetry？

Poetry 是一個現代化的 Python 專案管理工具，能同時處理 依賴套件管理 與 虛擬環境建立，非常適合專業開發使用。

4-3-2. 安裝 Poetry

執行以下指令來安裝：

curl -sSL https://install.python-poetry.org | python3 -

安裝完成後可用以下指令確認：

poetry --version

4-3-3. 使用 Poetry 建立專案與虛擬環境

1. 建立新專案資料夾

mkdir poetry_project
cd poetry_project

2. 初始化 Poetry 專案

poetry init

• 依照互動式提示輸入資訊
• 會建立 pyproject.toml 設定檔

3. 安裝並建立虛擬環境

poetry install

4. 啟用虛擬環境

poetry shell

5. 安裝套件

poetry add requests
poetry add numpy@latest

6. 退出虛擬環境

exit

4-4. venv 與 Poetry 的比較

小結：

• 想快速建立簡單虛擬環境 → 使用 venv
• 想自動管理依賴與版本 → 使用 Poetry

4-5. 小結

透過虛擬環境，可更有效地管理 Python 套件與版本。無論是簡單專案還是大型應用，venv 或 Poetry 都能協助你維持乾淨且一致的開發環境。

• venv：適合需要輕量虛擬環境的使用者（Python 內建）
• Poetry：適合需要自動依賴管理與版本鎖定的進階使用者

下一章將說明 版本管理與依賴管理的最佳實踐，進一步優化你的開發流程。

5. Python 版本與依賴管理的最佳實踐

了解 Python 的版本與虛擬環境管理之後，本章將介紹在實際開發中非常實用的最佳實踐技巧。透過正確的管理方式，可以避免環境混亂，提高開發效率，並讓團隊協作更順利。

5-1. 每個專案建立專屬虛擬環境

Python 最佳實踐之一，就是每個專案都建立獨立的虛擬環境。如果直接在系統的 Python 安裝套件，會容易造成衝突與環境污染。

5-1-1. 推薦的管理方式

1. 每個專案建立虛擬環境

python3 -m venv venv

2. 啟用虛擬環境

source venv/bin/activate  # macOS/Linux
venv\Scripts\activate  # Windows

3. 安裝必要套件

pip install requests pandas

✅ 小提示：

• 虛擬環境可防止跨專案的套件干擾。
• 在團隊中也能建立一致的環境，避免「在我電腦可以跑」的情況。

5-2. 明確管理依賴套件

為了讓專案能在其他環境中正確運作，明確紀錄並管理所有依賴套件 是不可或缺的。

5-2-1. 使用 requirements.txt

使用 pip freeze 可將當前虛擬環境中安裝的套件輸出為清單，方便他人重建相同環境。

1. 輸出目前的依賴套件清單

pip freeze > requirements.txt

2. 在其他環境中安裝相同套件

pip install -r requirements.txt

✅ 優點：

• 可將專案依賴準確地分享給他人
• 在部署或搬遷環境時也可快速重建

5-2-2. 使用 pyproject.toml（Poetry）

若使用 Poetry，可透過 pyproject.toml 管理依賴，並搭配 poetry.lock 固定版本。

1. 新增套件

poetry add numpy pandas

2. 檢視依賴檔案

pyproject.toml
poetry.lock

✅ 優點：

• 比 requirements.txt 更結構化
• 能精準鎖定版本，提升環境一致性

5-3. 區分開發與正式環境

開發過程中可能會使用額外工具（如 linters、測試框架），這些套件不應出現在正式環境中。

5-3-1. 使用 requirements-dev.txt

將開發用的工具分離出來，讓正式環境更乾淨、更安全。

範例：

pip freeze > requirements-dev.txt

正式部署時只需使用 requirements.txt，開發者可另行安裝 requirements-dev.txt。

5-4. 團隊開發中的環境統一

在多人開發中，環境不一致常是錯誤根源。以下幾點可以協助統一開發環境。

5-4-1. 統一 Python 版本

• 使用 pyenv 指定團隊使用相同的 Python 版本
• 可於專案根目錄建立 .python-version 文件

範例：

echo "3.10.4" > .python-version

5-4-2. 使用 .venv 目錄

將虛擬環境放在專案內部的 .venv（隱藏目錄）中，有助於 Git 管理。

範例：

python3 -m venv .venv

並在 .gitignore 中加入：

.venv/

5-5. 常見問題與解法

5-5-1. 使用 pyenv 後無法切換版本

解法： 執行 pyenv init 並設定 shell：

pyenv init

確認 PATH 設定正確。

5-5-2. 無法啟用 venv 虛擬環境

解法： 在 Windows 上可能需要變更 PowerShell 的執行權限：

Set-ExecutionPolicy Unrestricted -Scope Process

5-5-3. 已安裝套件卻無法 import

解法： 確認是否已啟用虛擬環境：

which python
which pip

結果應該指向虛擬環境路徑。

5-6. 小結

透過正確的版本與依賴管理，可以有效提升開發體驗與系統穩定性。

✅ 最佳實踐重點整理：

1. 每個專案建立獨立虛擬環境
2. 使用 requirements.txt 或 pyproject.toml 管理依賴
3. 區分開發與正式環境
4. 統一團隊開發者的 Python 版本與環境

6. 常見問題（FAQ）

關於 Python 的版本管理與虛擬環境使用，即使是有經驗的開發者也經常會遇到疑問。本章整理了一些常見問題，並提供具體解答，協助你更順利地進行開發與環境維護。

6-1. 可以同時使用多個 Python 版本嗎？

可以的！
使用像 pyenv 或 asdf 等工具，就能讓不同版本的 Python 共存在系統中，並依專案切換使用。

解法：使用 pyenv

1. 安裝不同版本的 Python：

pyenv install 3.9.7
pyenv install 3.10.4

2. 設定全域或本地版本：

pyenv global 3.10.4  # 全系統預設版本
pyenv local 3.9.7  # 指定專案資料夾使用特定版本

✅ 小提示： 使用 pyenv 不會更動系統原生的 Python，可放心操作。

6-2. 要怎麼刪除虛擬環境？

只要刪除對應的資料夾即可，不會影響系統。

如果使用的是 venv：

rm -rf venv  # macOS/Linux
rd /s /q venv  # Windows

如果使用的是 Poetry：

poetry env remove python

✅ 補充： 即使刪除虛擬環境，只要保留 requirements.txt 或 pyproject.toml，都可以快速重建環境。

6-3. 如何為特定專案使用不同版本的 Python？

使用 pyenv 或 venv 都可以實現。

使用 pyenv 的方法：

1. 在專案資料夾中指定版本：

pyenv local 3.8.10

2. 確認是否正確套用：

python --version
# 預期輸出：Python 3.8.10

使用 venv 的方法：

1. 使用指定版本建立虛擬環境：

python3.8 -m venv venv38
python3.10 -m venv venv310

2. 啟用對應環境：

source venv38/bin/activate  # 使用 Python 3.8 的環境

✅ 小提示： pyenv 適合快速切換版本，venv 則適合分離專案環境。

6-4. 要根據什麼條件選擇版本管理工具？

✅ 小提示： 依照開發類型選擇工具，可大幅簡化環境管理。

6-5. 使用 pyenv 但 python --version 沒有反映變更？

這通常是 shell 沒有正確初始化 pyenv。

解法：

1. 執行 pyenv 的初始化指令：

pyenv init

2. 將以下內容加入 .bashrc 或 .zshrc：

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv virtualenv-init -)"

3. 重新載入設定：

source ~/.bashrc  # 或 source ~/.zshrc

✅ 確認是否成功： 執行 python --version 應顯示正確版本。

6-6. 該用 venv 還是 Poetry？

結論：

• 要快速建立虛擬環境 → 用 venv
• 想自動管理依賴與版本 → 用 Poetry

✅ 備註： Poetry 雖然稍有學習曲線，但對中大型專案非常有幫助。

6-7. 如何將已安裝的套件固定在專案中？

可使用 pip freeze 將套件清單輸出為 requirements.txt：

pip freeze > requirements.txt

之後，在其他環境可透過：

pip install -r requirements.txt

✅ 好處： 可重現原始環境，提升部署與協作效率。

6-8. 小結

本章解答了在實際操作中常見的問題，幫助你更順利地進行 Python 環境與版本管理。

✅ 重點整理：

• 要管理多版本 → 用 pyenv
• 建立專案獨立環境 → 用 venv 或 Poetry
• 固定依賴套件版本 → 用 requirements.txt 或 pyproject.toml
• 在 Windows 環境可使用 pyenv-win 並確認環境變數設定

有了這些知識，你將能更自信地管理開發環境，打造穩定又高效的 Python 專案！

7. 結論與總結

透過本篇指南，相信你已經掌握了 Python 版本與虛擬環境的管理方法，並了解如何根據不同開發需求選擇最合適的工具。

無論是單人開發還是多人團隊合作，只要善用版本管理與依賴管理工具，就能大幅降低環境錯誤、提升開發效率，並讓專案維護更穩定長久。

7-1. 本文回顧

• 版本管理的必要性： 避免系統衝突、專案環境不一致、套件不相容等問題。
• 常見工具： pyenv、venv、Anaconda、asdf 各有特色與適用場景。
• 虛擬環境的重要性： 能讓每個專案維持獨立、乾淨的執行環境。
• 依賴管理方式： 使用 requirements.txt 或 pyproject.toml 明確記錄與還原環境。
• 團隊開發的最佳實踐： 統一 Python 版本、隔離虛擬環境、版本控制檔案忽略設定等。

7-2. 推薦的開發流程範例

以下是一個建議的開發步驟，可作為日常使用的參考：

1. 使用 pyenv 安裝並切換到專案指定的 Python 版本
2. 使用 venv 或 Poetry 建立虛擬環境
3. 安裝必要的套件與依賴
4. 將依賴記錄為 requirements.txt 或 pyproject.toml
5. 撰寫程式與版本控制（例如 Git）
6. 共享專案時，僅提供程式碼與依賴清單，不包含虛擬環境本體

7-3. 結語

Python 的環境與版本管理看似複雜，但只要建立正確的習慣，便能在日常開發中帶來極大助益。

從簡單的單人專案，到需要高度一致性的大型團隊開發，良好的版本與虛擬環境管理都是成功的關鍵。

希望這篇教學能成為你學習與實作的實用參考。若本篇內容對你有幫助，歡迎收藏或分享給更多開發者！