1. 介紹
為什麼 Python 的套件管理很重要？
Python 是一種語法簡單且易讀的程式語言，從初學者到專業工程師都廣泛使用。然而，實際開始開發時，常常會遇到「這段程式碼不知為何無法運作」「找不到模組」這樣的障礙。其中許多原因，都在於套件的管理方法。 在 Python 中，僅使用標準函式庫就能完成的開發很少見，在許多情況下都需要額外安裝外部套件（函式庫）來使用。此時，如果正確安裝、管理和更新套件的機制不完善，就會導致專案崩壞，或是與他人共同開發時出現障礙。不以「pip install」為止的套件管理世界
對於初次接觸 Python 的人來說，「用pip install安裝就 OK」的想法是很自然的。確實，僅此而已就能輕鬆新增函式庫。然而，當專案增加時，- 其他專案與套件的版本衝突
- 舊版本導致錯誤發生
- 只在生產環境無法正常運作
會面臨這樣的問題。這是套件管理知識不足所引發的典型麻煩。本篇文章可以學習的內容
本篇文章將以初學者也能輕鬆理解的方式，系統性地說明 Python 的套件管理。具體來說，將處理以下內容：- Python 中的「套件」是什麼？
- pip、venv、Poetry 等工具的使用區分方式
- 使用虛擬環境的原因及其活用方法
- 套件管理中容易發生的錯誤及其應對方法
- 常見問題及其解答
不僅是單純的使用方法列舉，還會觸及為什麼需要這麼做、該如何選擇等背景，一邊說明。
2. Python 中的套件是什麼？
套件是什麼？與模組的差異
Python 中的「套件」是指，將多個模組（Python 檔案）彙整在一起的目錄結構的程式庫。在 Python 中，為了提高再利用性，便利的函數或類別以檔案單位作為模組提供，進一步整理・構成這些的就是「套件」。 例如，requests 這個處理 HTTP 通訊的熱門套件中，包含多個檔案（＝模組），這些檔案作為一個套件運作。| 術語 | 內容 |
|---|
| 模組 | .py 副檔名的 Python 檔案（例：math.py） |
| 套件 | 彙整模組的資料夾結構（包含 __init__.py） |
使用套件的理由
在 Python 開發進展中，套件是不可或缺的。因為僅靠標準程式庫無法補足的功能（資料解析、機器學習、Web 通訊等），透過使用外部套件就能輕鬆導入・實作。 此外，Python 社群有許多優秀的套件，有助於高效的開發和高品質程式碼的實現。Python Package Index（PyPI）是什麼？
許多套件都在「PyPI（Python Package Index）」這個官方儲存庫公開。PyPI 是彙整全球開發者建立・公開的 Python 套件的巨大資料庫，使用 pip 指令就能從這裡輕鬆安裝套件。pip install numpy
執行上述指令時，pip 會參照 PyPI 搜尋 numpy 套件，並進行下載・安裝。pip 安裝套件的機制
pip 是 Python 官方的套件管理工具，以以下流程運作。- 參照 PyPI（或指定 URL）取得套件資訊
- 下載最新或指定版本的套件
- 若有必要的依賴套件，則一併安裝
- 儲存至本機環境的
site-packages 資料夾
安裝後，在 Python 腳本中可以如下使用。import numpy as np
arr = np.array([1, 2, 3])
print(arr)
總結：理解套件是避免問題的第一步
透過理解 Python 中套件的機制，就能預防「找不到模組」「舊版本無法運作」等常見問題。下一節將更詳細說明用來導入・管理此類套件的基礎工具「pip」。3. 基本的套件管理工具「pip」
pip 是什麼？
pip是 Python 中最基本的套件管理工具。從 Python 3.4 開始，它已標準安裝，無需額外設定即可使用。主要角色包括 外部套件的安裝、解除安裝、升級、列表顯示 等。 pip 的名稱是「Pip Installs Packages」的縮寫，正如其名所示，它是 Python 套件安裝的命令列工具。pip 的基本指令與用法
以下彙整 pip 中常用且具代表性的指令及其用途。| 指令 | 說明 |
|---|
pip install 套件名 | 安裝套件 |
pip uninstall 套件名 | 解除安裝套件（刪除） |
pip list | 顯示目前安裝的套件清單 |
pip show 套件名 | 顯示指定套件的詳細資訊 |
pip freeze | 顯示已安裝套件與版本（後述的 requirements.txt 中使用） |
pip install -r requirements.txt | 一括安裝多個套件（專案分享時便利） |
使用範例（命令列）：
pip install requests
pip list
pip uninstall requests
requirements.txt 是什麼？
requirements.txt 是 專案中使用的套件及其版本資訊彙整的檔案。在多人開發或將專案移至其他環境時，這個檔案非常方便。 內容會如下所示：requests==2.31.0
numpy>=1.24
使用此檔案，即可透過以下指令進行一括安裝。pip install -r requirements.txt
升級與版本指定
pip 可以進行套件的 升級 或 版本指定。pip install --upgrade 套件名
pip install 套件名==1.2.3
相依性問題與注意事項
pip 雖然簡單易用，但管理複雜相依性時較弱。例如，某套件所需版本與另一套件要求版本衝突的情況。 其結果， 可能導致此類問題。為避免此類問題，可導入後述的虛擬環境（venv）或更進階工具（Poetry 等）。總結：pip 是基礎，但不可過度依賴
pip 是 Python 開發的基礎中的基礎，在小型腳本或個人開發中，有時僅此即可足夠。然而，在相依性複雜化或開發環境差異的專案中，僅用 pip 管理會變得困難 的情況也有。下一節將詳細說明解決此類問題的「虛擬環境（venv）」用法。
4. 使用虛擬環境（venv）的理由與用法
為什麼需要虛擬環境？
在 Python 開發過程中，常見每個專案使用的套件種類或版本不同。例如：- 專案 A 使用
Django 3.2 - 專案 B 使用
Django 4.0
在這種情況下，如果將套件安裝到整個系統，就會發生升級一方時另一方無法運作的問題。為了避免此問題而引入的就是「虛擬環境」。 使用虛擬環境，可以為每個專案進行獨立的套件管理，實現不與其他環境干涉的開發。什麼是 venv？
venv 是 Python 標準的虛擬環境建立工具。從 Python 3.3 開始標準搭載，不需要額外安裝。使用 venv，可以為每個專案建立獨立的 Python 執行環境與套件群。venv 的基本操作
1. 虛擬環境的建立
在任意的專案資料夾內執行以下指令。python -m venv venv
此指令會建立名為「venv」的資料夾，並建構虛擬環境（資料夾名稱任意，但慣例使用 venv）。2. 虛擬環境的有效化
venv/Scripts/activate
source venv/bin/activate
有效化成功時，終端機開頭會顯示 (venv) 等。3. 虛擬環境的無效化
要離開虛擬環境時，執行以下指令。deactivate
4. 虛擬環境的刪除
虛擬環境僅是資料夾，因此只需刪除 venv 目錄即可。rm -r venv # mac/Linux
rd /s /q venv # Windows
使用 venv + pip 安全地建構環境
在虛擬環境有效化的狀態下執行 pip install，套件會安裝到虛擬環境內，不會影響整個系統。因此，可以防止對本番環境或別的專案的惡影響。source venv/bin/activate
pip install requests
在此狀態下安裝的程式庫，在離開虛擬環境（deactivate）後就無法使用了。與 IDE 的聯動（VSCode 等）
近年許多工程師使用的 Visual Studio Code（VSCode）等編輯器，具有自動偵測虛擬環境，並為每個專案切換 Python 執行環境的功能。與 venv 結合，可以大幅提升開發效率與環境穩定性。總結：虛擬環境是 Python 開發的基礎技能
Python 的虛擬環境（venv）是避免套件版本衝突或環境問題的必備技能。與 pip 結合使用，可以建構安全且可重現的開發環境。
5. 依賴關係管理工具「Poetry」的活用
pip 和 venv 單獨使用不足的原因
pip 和 venv 是 Python 開發中的基本工具，但當專案變得複雜或需要團隊開發時，會出現以下挑戰。- 依賴關係增加時，
requirements.txt 容易變成手動管理 - 在多個環境中重現套件的狀態很困難
- 套件的公開與建置很麻煩
應對這些挑戰的，就是名為 Poetry（Poetry） 的套件與專案管理工具。Poetry 是什麼？
Poetry 是一款現代化的工具，能夠整合管理 Python 專案的 依賴關係・虛擬環境・套件公開。它具有以下特點：- 在
pyproject.toml 中一元管理依賴資訊 - 自動建立和管理虛擬環境
- 無需手動設定
pip 或 venv - 也能建置和公開套件（支援 PyPI）
使用 Poetry，即可實現 「專注於撰寫程式碼」 的開發環境。Poetry 的安裝方法
Poetry 使用官方腳本安裝。執行以下指令，即可依據 OS 安裝。curl -sSL https://install.python-poetry.org | python3 -
安裝後，可用以下指令確認版本：poetry --version
使用 Poetry 建立專案與依賴管理
1. 專案的新規建立
poetry new 專案名稱
此指令會自動產生以下 Python 專案的雛形。專案名稱/
├── pyproject.toml
├── README.rst
├── 專案名稱/
│ └── __init__.py
└── tests/
└── __init__.py
2. 在現有專案中使用 Poetry 的情況
在現有的資料夾中執行以下：poetry init
以對話形式註冊依賴關係，並產生 pyproject.toml。3. 套件的新增・刪除
poetry add requests
poetry remove requests
4. 虛擬環境的自動建立與執行
Poetry 在新增依賴關係時，會自動建立虛擬環境。以下可進入該環境：poetry shell
虛擬環境內即可使用 Python 和 pip。5. 透過鎖定檔案確保再現性
Poetry 會將依賴關係的資訊記錄在名為 poetry.lock 的檔案中。藉此，其他開發者即可重現完全相同的環境。poetry install
此指令可基於 pyproject.toml 和 poetry.lock 建置精確的環境。pyproject.toml 的角色
在 Poetry 中，不使用傳統的 setup.py 或 requirements.txt，而是將所有設定集中在單一檔案 pyproject.toml 中。 範例：[tool.poetry]
name = "myproject"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
[tool.poetry.dependencies]
python = "^3.10" requests = "^2.31.0"
[build-system]
requires = ["poetry-core"] build-backend = "poetry.core.masonry.api"
藉由此結構，即可實現 以程式碼管理專案狀態 的理想環境。總結：Poetry 是現代開發的強力夥伴
Poetry 能從傳統 pip 和 venv 的繁瑣管理中解放，提供強大的開發支援工具。特別推薦給以下人士：- 進行多人開發的人
- 希望明確化套件依賴關係的人
- 希望自動化虛擬環境建置的人
- 未來希望公開套件的人
6. 與其他工具的比較（Poetry vs pipenv vs conda）
套件管理工具應依用途選擇
Python 的套件管理，除了 pip 和 venv 之外，還有幾個方便的工具。代表性的有以下三個：- Poetry：依賴關係管理＋套件建置強大的現代工具
- Pipenv：pip 和 venv 的中間存在。對初學者友善但有些不穩定
- conda：資料科學導向的環境建置強大，可管理 Python 以外的語言
各自都有優點和缺點，因此，依專案目的或開發風格選擇最適合的工具非常重要。各工具的比較表
以下以表格彙整 Poetry・Pipenv・conda 的主要差異：| 項目 | Poetry | Pipenv | conda |
|---|
| 虛擬環境的管理 | 自動建立・管理 | 自動建立・管理 | 專屬環境（conda） |
| 依賴關係的明確化 | pyproject.toml & poetry.lock | Pipfile & Pipfile.lock | environment.yml |
| Python 以外的語言對應 | ✕ | ✕ | ◯（R、C、Java 等） |
| 套件的建置・公開 | ◯（PyPI 對應） | △（無法公開） | ✕ |
| 跨平台對應 | ◯ | △（部分有問題） | ◯ |
| 開發的現代性・一致性 | ◎ | ○ | △（有些笨重） |
| 主要用途 | Web 開發・公開 | 初學者導向開發 | 資料分析・科學計算 |
各工具的特點與適合的情境
Poetry：實現開發者導向的最佳實務
Poetry 是最重視「作為專案的 Python 開發」的工具。依賴關係的管理、虛擬環境的自動化、套件的公開等，全都可一致管理，因此，在中級～上級開發者中非常受歡迎。 適合的人：- Web 應用程式或 API 等，正式開發 Python 製應用程式的人
- 想在 PyPI 公開自製套件的人
- 在團隊開發中重視組態檔案再現性的人
Pipenv：旨在取 pip 和 venv 的「優點」的工具
Pipenv 整合了 pip 和 venv 的功能，提供對初學者易於處理的 UI。使用 Pipfile 這種專屬格式管理依賴關係，並自動建立虛擬環境。 不過，更新頻率已降低，在部分環境中報告有不穩定動作或問題，因此最近轉向 Poetry 的案例增加中。 適合的人：- 對 pip 或 venv 稍有習慣的初學者
- 想從學習用或小規模專案開始的人
- 喜歡指令少且直覺的操作的人
conda：管理包含 Python 以外的廣泛環境
conda 是包含在 Anaconda 發行版中的套件管理工具，不限於 Python，還能管理 R 或 C 等環境。特別是在科學技術計算或資料分析的現場備受重視。 套件的依賴解決能力非常高，能輕鬆處理複雜的函式庫（NumPy、TensorFlow、OpenCV 等），這是很大的優點。 適合的人：- 想在資料科學、機器學習、統計解析領域活用的人
- 想同時管理 Python 以外的語言的人
- 在 Windows 環境中為套件依賴關係苦惱的人
選擇的指引
猶豫時，以以下方式思考就能更容易選擇。- 開發者・公開導向 → Poetry
- 學習目的・輕量環境 → Pipenv（或 venv＋pip）
- 資料分析・多語言環境 → conda
總結：依目的選擇工具是成功的關鍵
Python 的套件管理，因為工具豐富而容易迷失。不過，只要明確「要用在什麼目的」，最適合的工具自然會浮現。 Poetry・Pipenv・conda，各自有優點和適合的場景，依自己的開發風格或團隊體制選擇，就能建構更順暢且高再現性的開發環境。
7. 實踐例：專案別的環境建置步驟
為什麼環境建置步驟很重要？
即使知道套件管理工具的使用方法，如果不知道在實際專案中如何開始使用，那就沒有意義了。在這裡，我們將以兩種模式說明專案設定的步驟，讓初學者也能毫不猶豫地進行。- pip + venv 使用的基本建置方法
- Poetry 使用的智慧建置方法
模式①：使用 pip + venv 的專案建置
這是最基本的方法，推薦給剛開始 Python 的人。 步驟 1：建立專案資料夾mkdir my_project
cd my_project
步驟 2：建立並啟用虛擬環境python -m venv venv
source venv/bin/activate # Windows 的情況下使用 venv\Scripts\activate
步驟 3：安裝必要的套件pip install requests numpy
步驟 4：將依賴套件寫入 requirements.txtpip freeze > requirements.txt
步驟 5：停用虛擬環境deactivate
以這種配置，其他開發者就能根據requirements.txt來重現環境：python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
模式②：使用 Poetry 的專案建置
使用 Poetry 後，就不需要手動管理虛擬環境或依賴關係，能夠進行高效的開發。 步驟 1：專案初始化poetry new my_project
cd my_project
這樣就會自動產生以下結構。my_project/
├── pyproject.toml
├── README.rst
├── my_project/
│ └── __init__.py
└── tests/
└── __init__.py
步驟 2：新增必要的程式庫poetry add requests numpy
Poetry 會在這個階段自動建立虛擬環境，並在pyproject.toml和poetry.lock中記錄依賴關係。 步驟 3：進入虛擬環境（選用）poetry shell
步驟 4：其他人重現環境的方法 在分享專案時，只需以下指令就能重現相同的環境：poetry install
這樣，所有依賴關係就會精確安裝，虛擬環境也會自動產生。應該選擇哪種方法？
| 情境 | 推薦工具 |
|---|
| 學習目的，首先想熟悉 Python | pip + venv |
| 團隊開發，需要明確化與自動化依賴關係 | Poetry |
| 考慮公開或發佈程式庫 | Poetry |
| 輕量的一時腳本或驗證 | pip（無虛擬環境）也可以 |
補充：與 VSCode 等 IDE 的整合
Visual Studio Code 或 PyCharm 等 IDE 具有自動辨識虛擬環境或 Poetry 虛擬環境的功能。開啟專案資料夾後，會自動選擇適當的 Python 解釋器，因此在編輯器上也能毫不猶豫地切換環境。總結：一致的環境建置才是品質與重現性的關鍵
在 Python 開發中，無論誰製作都能以相同方式運作的環境是非常重要的。正確使用 pip + venv 或 Poetry 就能實現這一點。
8. 常見錯誤與對策
為什麼套件管理容易發生錯誤？
Python 雖然是一種靈活的語言，但由於套件的版本、依賴關係以及虛擬環境的差異，容易發生意想不到的錯誤。特別是初學者容易遇到的問題，有幾種模式存在。 在這裡，我們介紹典型的錯誤及其解決方法。錯誤①：ModuleNotFoundError – 找不到模組
錯誤內容：ModuleNotFoundError: No module named 'requests'
原因：- 套件未安裝
- 未啟用虛擬環境
- 在不同的 Python 環境中執行
對策：pip install requests
source venv/bin/activate # 或 venv\Scripts\activate
- 如果使用 VSCode 等 IDE 執行，確認 Python 解釋器的選擇
錯誤②：pip install 時發生 Permission denied 或存取拒絕
錯誤內容（例）：PermissionError: [Errno 13] Permission denied: '/usr/lib/python3.x/site-packages/...'
原因：- 試圖在全域環境中安裝套件
- 以無管理員權限的使用者執行
對策：- 確認是否在虛擬環境中作業
- 如果一定要在全域環境執行，則附加
--user 選項
pip install --user 套件名稱
- Mac/Linux 的情況下，需要管理員權限的操作使用
sudo（不推薦）
錯誤③：版本衝突（依賴關係衝突）
錯誤內容（例）：ERROR: Cannot install X==1.2.0 and Y==2.0.0 because these package versions have incompatible dependencies.
原因： 對策：- 使用
pipdeptree 等工具來視覺化並確認依賴關係 - 使用 Poetry 或 conda 等能自動解決依賴關係一致性的工具
- 如果衝突無法解決，則分開使用虛擬環境來運作
錯誤④：從 requirements.txt 安裝失敗
錯誤內容：ERROR: Could not find a version that satisfies the requirement X==1.0.0
原因：requirements.txt 中記載的版本不存在或已被廢止- 與自己的 Python 版本不相容
對策：- 在 PyPI 確認目標套件和版本的存在
- 根據 Python 的版本指定相容的版本
- 使用 Poetry 的情況下，可以使用
poetry update 來更新一致的依賴關係
錯誤⑤：虛擬環境無法正常運作或無法啟用
錯誤內容（例）：source: command not found
原因：- 在 Windows 上使用 Unix 系指令
- 建立虛擬環境時路徑錯誤
對策：# macOS / Linux
source venv/bin/activate
# Windows
venv\Scripts\activate
rm -r venv
python -m venv venv
補充：pip 版本過舊時的不便
pip 本身的版本過舊時，無法對應 PyPI 的最新規格，導致安裝失敗。 對策：pip install --upgrade pip
定期升級可以更容易防止未來的錯誤。總結：了解「機制」就不怕錯誤
套件管理相關錯誤大多源自「環境」「依賴關係」「Python 的版本」。不要慌張地試圖各種方法對應，而是解讀錯誤訊息並理解機制來對應，這是 Python 進步的捷徑。
9. 常見問題（FAQ）
Q1. pip和Poetry，應該使用哪一個？
A. 對於小型腳本或學習專案，使用pip和venv的組合就足夠了。然而，在多人開發或套件依賴關係複雜的情況下，Poetry在依賴關係管理上更容易且再現性更高，因此推薦使用。Q2. 虛擬環境一定要使用嗎？
A. 不是必須的，但強烈推薦使用。如果不使用虛擬環境，就會影響系統整體的Python環境，容易發生與其他專案依賴關係衝突等問題。Q3. pyproject.toml和requirements.txt的差異是什麼？
A.requirements.txt：pip使用的簡單文字格式依賴清單pyproject.toml：Poetry等工具使用的結構化設定檔案（依賴關係＋中繼資料）
requirements.txt強調安裝的再現性，pyproject.toml適合專案整體的構成管理。Q4. pipenv和Poetry哪一個比較主流？
A. 目前Poetry的開發更活躍，在可靠性和功能面也更優越。pipenv曾經一度流行，但由於更新停滯和故障報告增加，逐漸轉向Poetry。Q5. conda和pip可以併用嗎？
A. 基本上可以併用，但需要注意依賴關係的一致性。在conda環境中，盡量使用conda指令安裝套件，只有conda沒有時才使用pip，這樣可以避免問題。Q6. 虛擬環境建立太多，管理起來很麻煩。怎麼辦？
A. 使用Poetry的話，虛擬環境的建立和刪除會自動進行，因此手動管理的負擔會大幅減輕。另外，要確認虛擬環境清單或位置，可以使用以下指令：poetry env list
poetry env remove <環境名稱>
Q7. requirements.txt或pyproject.toml應該加入Git嗎？
A. 是的，為了確保專案的可再現性，必須包含這些檔案。包含這些檔案後，其他開發者就能輕鬆重現相同的環境，讓團隊開發更順暢。Q8. 可以將生產環境和開發環境的套件分開管理嗎？
A. Poetry可以明確區分開發用和生產用的依賴關係進行管理。例如，可以將測試框架等限定為開發用安裝：poetry add pytest --group dev
這樣，生產環境就不需要安裝不必要的工具了。Q9. 發生錯誤時該怎麼辦？
A. 首先冷靜閱讀錯誤訊息，並確認以下重點。- 虛擬環境是否已啟用？
- 使用的Python版本是否相容？
- 該套件是否存在於PyPI？
另外，請務必參考本章的「8. 常見錯誤與對策」區段。Q10. 專案有多人開發時，需要注意什麼？
A. 最重要的是「讓環境可再現」。徹底執行以下事項，就能避免問題：- 使用虛擬環境
- 分享
requirements.txt 或 pyproject.toml / poetry.lock - 明確指定Python版本（例如：Python 3.10以上）
活用Poetry，就能相對輕鬆實現這些。
