開發者必學：使用 pyenv 輕鬆管理多版本 Python 並結合 virtualenv 打造隔離環境

1. 什麼是 pyenv？

對於 Python 開發者而言，經常需要針對不同的專案使用不同版本的 Python。在這種情況下，pyenv 就是一個非常實用的工具。pyenv 是一款可以管理多個 Python 版本的工具，並且可以讓你針對不同的專案輕鬆切換所需的版本。

Python 版本管理的挑戰

隨著 Python 開發的深入，會有越來越多的專案需要使用不同的 Python 版本。舉例來說，有的專案可能需要使用 Python 3.9，而另外一個專案可能仍需使用 Python 2.7。一般來說，系統中通常只安裝了一個版本的 Python，因此版本之間的切換相當麻煩。這個問題就可以透過 pyenv 來解決。

pyenv 的優點

使用 pyenv 有以下幾個好處：

輕鬆切換版本：使用 pyenv，可以針對整個系統或單一專案輕鬆切換 Python 版本。
管理多個版本：可以用一個指令管理系統中已安裝的多個 Python 版本，讓你能夠更靈活地應對每個專案所需的相依性與版本差異。
支援多種作業系統（不包含 Windows）：可在 macOS 與 Linux 等多種作業系統上使用。

pyenv 的運作原理

pyenv 會為每個版本的 Python 建立一個獨立的目錄，並將該版本的 Python 安裝於其中。使用者可透過 pyenv global 或 pyenv local 指令，指定整個系統或特定專案所要使用的 Python 版本。

2. 如何安裝 pyenv

概述

若要使用 pyenv，首先必須在系統中安裝它。本章節將介紹在 macOS 與 Linux 環境中安裝 pyenv 的方法。由於 pyenv 不支援 Windows 環境，因此建議 Windows 使用者採用其他方式，例如 WSL 或 Anaconda。

在 macOS 上的安裝步驟

在 macOS 上，可以透過 Homebrew 輕鬆安裝 pyenv。Homebrew 是 macOS 的套件管理工具，可以簡單地安裝各種軟體。請依照以下步驟進行安裝。

確認是否已安裝 Homebrew 首先，請確認系統中是否已安裝 Homebrew。打開終端機並執行下列指令：

   brew --version

如果顯示版本資訊，表示已經安裝好 Homebrew。若尚未安裝，請前往官方網站（Homebrew 官方網站）查看安裝說明。

安裝 pyenv 如果系統已安裝 Homebrew，請執行以下指令安裝 pyenv：

   brew install pyenv

安裝完成後，即可進行下一步設定。

設定環境變數 若要使用 pyenv，需在 Shell 中設定環境變數。通常會將設定加入 .bash_profile 或 .zshrc。請在終端機執行以下指令：

   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile
   echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile
   echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile

如果你使用的是 .zshrc，請將上述指令加到 .zshrc 中，而非 .bash_profile。設定完成後，請重新啟動終端機，或執行以下指令使設定生效：

   source ~/.bash_profile

確認是否安裝成功 設定完成後，請執行以下指令確認 pyenv 是否成功安裝：

   pyenv --version

若顯示版本號，即表示 pyenv 安裝成功。

在 Linux 上的安裝步驟

在 Linux 環境下，基本上與 macOS 的安裝流程相似，不過會使用 apt 或 yum 等套件管理工具。以下以 Ubuntu 為例介紹安裝流程。

安裝必要的套件 在安裝 pyenv 前，需要先安裝相依的開發套件。請執行以下指令安裝所需工具：

   sudo apt update
   sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev 
   libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev 
   xz-utils tk-dev libffi-dev liblzma-dev python-openssl git

安裝 pyenv 使用 Git 下載 pyenv 的原始碼並安裝：

   curl https://pyenv.run | bash

設定環境變數 為了讓 pyenv 正常運作，需在 .bashrc 或 .zshrc 中加入以下設定：

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

為使設定生效，請重新啟動終端機或執行 source ~/.bashrc。

確認是否安裝成功 請執行下列指令確認 pyenv 是否正確安裝：

   pyenv --version

故障排除

若在安裝 pyenv 的過程中出現錯誤，可能是因為系統缺少必要的相依套件。特別是在 Linux 環境中，不同的系統可能會需要不同的套件。建議參考官方文件並依照指示安裝所需套件。

3. 管理 Python 版本

安裝好 pyenv 之後，接下來需要學習如何實際管理 Python 版本。本章節將介紹如何使用 pyenv 安裝與切換不同的 Python 版本。

安裝 Python 版本

透過 pyenv 可以輕鬆安裝不同版本的 Python。例如，某個專案需要 Python 3.8，另一個專案需要 Python 3.9，可以分別使用以下指令進行安裝。

查看可用版本清單 首先，請使用 pyenv 檢視所有可安裝的 Python 版本。執行以下指令：

   pyenv install --list

這個指令會列出所有 pyenv 支援的 Python 版本，供你選擇安裝所需的版本。

安裝指定的 Python 版本 例如，若要安裝 Python 3.9.1，可使用以下指令：

   pyenv install 3.9.1

此指令會將 Python 3.9.1 安裝到系統中。如需安裝多個版本，請分別執行相對應的安裝指令。

切換 Python 版本

使用 pyenv 可以輕鬆切換已安裝的多個 Python 版本。這樣可以根據不同專案使用對應的版本，避免相依性問題。

切換系統預設版本 若要更改整個系統使用的 Python 版本，請執行以下指令：

   pyenv global 3.9.1

此指令會將 Python 3.9.1 設為系統預設版本，所有目錄中預設皆會使用此版本。

切換特定專案的版本 若只想在某個目錄（專案）中使用特定版本，可使用 pyenv local 指令：

   pyenv local 3.8.0

此指令會讓目前所在的目錄中使用 Python 3.8.0，而其他目錄仍使用 pyenv global 設定的版本。

確認目前使用的版本 想要確認目前系統或專案所使用的 Python 版本，可執行以下指令：

   pyenv version

這個指令會顯示目前有效的 Python 版本資訊，包括是全域還是區域的設定。

移除不需要的版本

若某個專案結束或誤安裝了某個 Python 版本，可以透過 pyenv 簡單地移除它。

移除安裝的版本 執行以下指令，即可刪除已安裝的特定版本：

   pyenv uninstall 3.9.1

此指令會將 Python 3.9.1 從系統中移除。

4. 搭配 virtualenv 使用

pyenv 能夠有效地管理 Python 版本，而若想進一步管理每個專案的相依套件，則建議與 virtualenv（虛擬環境）搭配使用。本章節將說明如何同時使用 pyenv 和 virtualenv，並介紹這樣做的便利性。

什麼是 virtualenv？

virtualenv 是一個可以為每個 Python 專案建立獨立虛擬環境的工具，用來隔離各自的函式庫與套件相依性。這樣即使在同一台系統上開發多個專案，也不會因版本衝突而互相干擾。例如，專案 A 需要使用 requests 2.0，而專案 B 則使用 3.0，就可以為這兩個專案建立各自的獨立虛擬環境。

pyenv 與 virtualenv 的差異

pyenv 主要用於管理 Python 的版本，可以針對整個系統或個別專案設定不同版本的 Python；而 virtualenv 則是用於在虛擬環境中管理 Python 的函式庫與套件相依性。結合 pyenv 與 virtualenv 使用，可獲得以下好處：

管理多個 Python 版本：使用 pyenv 安裝不同版本的 Python，並針對每個專案設定最適合的版本。
為每個專案分離相依套件：使用 virtualenv 為每個專案建立獨立環境，避免套件版本衝突。

安裝 pyenv-virtualenv

除了安裝 pyenv 之外，還可以安裝其插件 pyenv-virtualenv，使建立與管理虛擬環境變得更加方便。請依照以下步驟安裝。

安裝方式 在 macOS 上可以使用以下指令：

   brew install pyenv-virtualenv

若使用 Linux，可使用下列指令：

   git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

設定環境變數 安裝完成後，需將以下設定加到你的 Shell 啟動檔中（如 .bash_profile）：

   echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bash_profile
   source ~/.bash_profile

建立虛擬環境

使用 pyenv-virtualenv 可以根據指定版本的 Python 建立虛擬環境。以下示範如何建立使用 Python 3.8.0 的虛擬環境：

pyenv virtualenv 3.8.0 my_project_env

上述指令將建立一個名稱為 my_project_env、基於 Python 3.8.0 的虛擬環境。

切換虛擬環境

要在專案中啟用某個虛擬環境，可使用 pyenv local 指令：

pyenv local my_project_env

執行後，該虛擬環境會在當前資料夾中生效，而其他資料夾則繼續使用全域設定的版本。

刪除虛擬環境

若不再需要某個虛擬環境，可使用以下指令將其刪除：

pyenv uninstall my_project_env

virtualenv 的便利性

結合 pyenv 與 virtualenv 使用，能夠完全分離各個專案的 Python 版本與套件依賴，避免版本衝突，並維持穩定的開發環境。

5. 使用 pyenv 時的注意事項

利用 pyenv 或 virtualenv 可以大幅提升 Python 版本與環境的管理效率，但在使用過程中，也有一些常見問題與需注意的事項。本章節將介紹使用 pyenv 時可能遇到的常見錯誤及對應的解決方法。

1. Windows 支援有限

pyenv 基本上是為 macOS 與 Linux 設計的，並不直接支援 Windows 環境。因此在 Windows 上使用會受到限制。如果你是 Windows 使用者，可以考慮以下替代方案：

使用 Windows Subsystem for Linux (WSL)：可在 Windows 上安裝 WSL，建構類似 Linux 的環境後使用 pyenv。
使用 Anaconda：若不使用 WSL，也可考慮使用 Anaconda 來管理 Python 版本與虛擬環境，這對 Windows 使用者來說是更友善的選擇。

2. 缺少相依套件導致錯誤

在 Linux 環境中安裝 pyenv 時，若缺少必要的依賴函式庫，可能會出現錯誤訊息。例如下列錯誤提示：

WARNING: The Python bz2 extension was not compiled. Missing the bzip2 lib?

解決方法：

安裝缺少的系統套件（例如：libbz2-dev 或 libssl-dev 等），然後重新執行 pyenv install。

sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev

3. 系統預設 Python 與 pyenv 發生衝突

有時系統預設的 Python 版本會與 pyenv 所管理的版本發生衝突。這通常是因為 PATH 設定或 shell 初始化設定不正確。 解決方法：

請確認你的 shell 啟動檔（如 .bashrc 或 .zshrc）中已正確加入以下設定：

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

設定後請重新啟動終端機，或執行 source ~/.bashrc 使設定生效。

4. 安裝特定版本失敗

某些特定版本的 Python 在安裝時可能會失敗，這通常是因為系統缺少編譯所需的工具或套件。 解決方法：

請安裝必要的系統套件，例如 build-essential、libssl-dev 等，再重新執行安裝指令。

5. Python 版本輸入錯誤

在使用 pyenv install 指令時，如果輸入了不存在或拼寫錯誤的版本號，將會導致錯誤。 解決方法：

請使用 pyenv install --list 先確認可安裝的版本，再輸入正確的版本號。

6. 虛擬環境衝突

當你使用多個虛擬環境，並且它們共用同一個 Python 版本時，可能會出現套件依賴衝突的情況。 解決方法：

請為每個專案建立獨立的虛擬環境，使用 virtualenv 或 pyenv-virtualenv 將環境完全分離。即使使用相同的 Python 版本，也應該讓每個專案擁有自己的環境，以避免衝突。

6. 總結與下一步

pyenv 是一個非常強大且實用的工具，特別適合需要在多個專案中切換不同 Python 版本的開發者。使用 pyenv 可以輕鬆切換版本、管理環境，大幅提升開發效率。再搭配 virtualenv 使用，更能有效分離各專案的相依套件，讓你在同一台機器上維持乾淨且穩定的開發環境。

pyenv 的應用總結

簡化版本管理：透過 pyenv，可以輕鬆針對整個系統或個別專案切換 Python 版本。
搭配虛擬環境使用：配合 pyenv-virtualenv 或 virtualenv，可以獨立管理每個專案的函式庫與相依性。
重視錯誤排除與設定：使用 pyenv 時，須注意相依套件、路徑設定、版本指定等問題，才能確保順利運作。

下一步建議

進一步提升開發效率：當你熟悉 pyenv 的基本操作後，可以考慮結合其他工具如 pipenv 或 poetry，進一步簡化依賴管理與自動化環境設定。
適應不同作業系統：如果你是 Windows 使用者，可以嘗試透過 WSL 建立 Linux 環境來使用 pyenv，或考慮改用 Anaconda 這類適合 Windows 的工具。
實際應用於專案：除了學習理論外，也建議在實際專案中導入 pyenv。無論是新專案或既有專案，都可以藉由 pyenv 與虛擬環境管理機制，體驗到更清晰、有效率的開發流程。

オープンソースの力を活用する方法～Ubuntuの世界へようこそ～

Ubuntuにおけるpyenvのセットアップと活用法｜Python環境管理ガイド

目次 1 1. はじめに1.1 Pythonバージョン管理の重要性1.2 Ubuntuとpyenvの組み合わせの利点2 …