Python - 模組與套件（Modules & Packages）

主題：第三方套件安裝（pip install）

---

簡介

在 Python 的生態系統中，第三方套件是讓開發者快速解決問題、提升開發效率的關鍵資源。無論是資料分析、網頁爬蟲、機器學習，還是系統管理，幾乎都有成熟、維護良好的套件可直接使用。
然而，要把這些套件帶入自己的專案，最常見也是最便利的方式，就是透過 Python 官方的套件管理工具 pip（Package Installer for Python）來安裝。掌握 pip 的基本用法與進階技巧，能讓你在開發過程中避免環境衝突、快速部署，進而專注於程式本身的邏輯。

本篇文章將從 pip 的安裝與使用、虛擬環境的配合、版本管理、常見問題 等面向，提供完整、實務導向的教學，適合剛接觸 Python 的新手，也能幫助已有基礎的開發者深化套件管理的概念。

---

核心概念

1. pip 是什麼？

• pip 是 Python 官方提供的套件安裝工具，隨 Python 3.4 之後的標準安裝包一起提供。
• 它會從 Python Package Index (PyPI) 下載套件，並自動處理相依套件的安裝。

小技巧：在命令列直接執行 python -m pip --version，可以確認目前使用的 pip 版本與所屬的 Python 直譯器。

2. 基本安裝指令

指令	說明
pip install package_name	安裝最新穩定版
pip install package_name==1.2.3	安裝特定版本
pip install "package_name>=1.0,<2.0"	安裝符合版本範圍的套件
pip install -r requirements.txt	依照需求檔一次安裝多個套件

註：在 Windows 上若有多個 Python 版本，建議使用 py -m pip 或明確指定 Python 路徑的方式，以免安裝到錯誤的環境。

3. 虛擬環境（Virtual Environment）

在同一台機器上，可能會有多個專案需要不同版本的套件。虛擬環境可以為每個專案建立獨立的 Python 執行環境，避免相依衝突。

• 建立虛擬環境

  python -m venv .venv          # 在專案根目錄建立 .venv 資料夾
  

• 啟用虛擬環境
  • Windows

    .venv\Scripts\activate
    

  • macOS / Linux

    source .venv/bin/activate
    

• 停用虛擬環境

  deactivate
  

提醒：啟動虛擬環境後，pip 會自動指向該環境內的 pip，確保套件只安裝在該專案裡。

4. 需求檔（requirements.txt）

在多人協作或部署時，將所有依賴寫入 requirements.txt，讓其他開發者或 CI/CD 系統可以一鍵復原相同環境。

• 產生需求檔

  pip freeze > requirements.txt
  

• 安裝需求檔裡的套件

  pip install -r requirements.txt
  

小技巧：若只想保留直接使用的套件，可手動編輯 requirements.txt，或使用 pipreqs 產生較精簡的需求檔。

5. 套件升級與移除

• 升級套件

  pip install --upgrade package_name
  

• 移除套件

  pip uninstall package_name
  

---

程式碼範例

以下示範在不同情境下使用 pip 的實務範例，均以 Python 為主要語言，並加上詳細註解。

範例 1：安裝 requests 並簡單發送 HTTP GET

# 先在終端機安裝套件
# pip install requests

import requests  # 引入第三方套件

def fetch_google():
    """使用 requests 取得 Google 首頁 HTML"""
    response = requests.get("https://www.google.com")
    # 檢查回應狀態碼
    if response.status_code == 200:
        print("成功取得網頁內容，長度:", len(response.text))
    else:
        print("發生錯誤，狀態碼:", response.status_code)

if __name__ == "__main__":
    fetch_google()

說明：安裝套件後，只要 import 即可直接使用，且不需要自行處理底層的 HTTP 連線細節。

範例 2：使用虛擬環境安裝指定版本的 pandas

# 建立虛擬環境
python -m venv data_env
# 啟用環境 (Windows)
data_env\Scripts\activate
# 啟用環境 (macOS / Linux)
source data_env/bin/activate

# 安裝 pandas 1.3.5（舊版，適用於某些舊版程式碼）
pip install pandas==1.3.5

# 在虛擬環境內執行的程式
import pandas as pd

df = pd.DataFrame({
    "城市": ["台北", "新竹", "高雄"],
    "人口": [2_646_000, 447_000, 2_773_000]
})
print(df)

重點：使用虛擬環境後，pip list 只會顯示該環境內的套件，避免與全域環境衝突。

範例 3：建立 requirements.txt 並在 CI 中自動安裝

# 產生需求檔（在已安裝套件的虛擬環境中執行）
pip freeze > requirements.txt

requirements.txt 內容示例：

Flask==2.2.5
gunicorn==20.1.0
requests>=2.28,<3.0

在 GitHub Actions（CI）中安裝：

# .github/workflows/python-app.yml
name: Python CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m venv .venv
          source .venv/bin/activate
          pip install -r requirements.txt
      - name: Run tests
        run: |
          source .venv/bin/activate
          pytest

說明：CI 透過 requirements.txt 保證每次測試使用相同的套件版本，提升可重現性。

範例 4：使用 pip install -e . 進行本地套件開發

假設你正在開發自己的套件 myutils，目錄結構如下：

myutils/
│─ myutils/
│   ├─ __init__.py
│   └─ helpers.py
│─ setup.py
│─ README.md

setup.py 簡易範例：

from setuptools import setup, find_packages

setup(
    name="myutils",
    version="0.1.0",
    packages=find_packages(),
    install_requires=[
        "requests>=2.28"
    ],
)

在開發階段使用 editable mode 安裝：

# 於 myutils 目錄執行
pip install -e .

此時，任何對 myutils 內部檔案的修改，都會即時反映在使用該套件的程式中，無需重新安裝。

# 使用自訂套件
from myutils.helpers import greet

greet("Python 學習者")

好處：讓套件開發與測試更順暢，特別適合在本機或團隊內部共享尚未上傳至 PyPI 的程式碼。

範例 5：檢查套件相依衝突（pip check）

當安裝多個套件時，可能會出現相依版本不相容的情況。pip check 能快速偵測：

pip install numpy==1.23.0 pandas==2.0.0
pip check

輸出可能類似：

pandas 2.0.0 has requirement numpy>=1.24.0, but you have numpy 1.23.0 which is incompatible.

此時，你可以調整版本或使用 pip install "numpy>=1.24,<2.0" 重新安裝。

---

常見陷阱與最佳實踐

陷阱	說明	解決方案 / 最佳實踐
全域安裝衝突	直接在系統 Python 安裝套件，會影響其他專案。	使用 虛擬環境 (venv、conda) 隔離套件。
版本不一致	團隊成員安裝的套件版本不同，導致程式在某些機器上失敗。	以 requirements.txt 鎖定版本；在 CI 中使用相同指令。
缺少相依套件	手動下載套件時忘記安裝相依套件，執行時出錯。	交給 pip 處理相依，或使用 pip install -r requirements.txt。
pip 版本過舊	舊版 pip 可能無法解析新格式的 pyproject.toml。	定期執行 python -m pip install --upgrade pip。
Windows 路徑問題	pip 指向錯誤的 Python 版本，或路徑中有空格。	使用 py -m pip 或完整路徑 C:\Python311\python.exe -m pip。
套件未在 PyPI	某些私有套件只能從 Git 或內部檔案安裝。	使用 pip install git+https://... 或 pip install ./local_pkg。

最佳實踐總結

1. 永遠在虛擬環境內安裝套件。
2. 使用 requirements.txt 版本鎖定，避免「在我機器上可以跑」的尷尬。
3. 定期升級 pip，確保支援最新的套件格式與安全性。
4. 檢查相依衝突 (pip check) 並在 CI 中加入測試。
5. 使用 editable mode (-e) 進行本地套件開發，提升迭代效率。

---

實際應用場景

場景	需求	典型 pip 操作
資料科學專案	需要 numpy、pandas、scikit-learn 等特定版本	pip install -r requirements.txt，或 pip install numpy==1.26.0 pandas==2.1.0
Web API 部署	使用 Flask + Gunicorn，且環境需與本機一致	建立 requirements.txt，在 Dockerfile 中 RUN pip install -r /app/requirements.txt
自動化測試 CI/CD	每次提交自動安裝相依、執行測試	在 GitHub Actions、GitLab CI 中使用 pip install -r requirements.txt
內部工具開發	團隊共享自製套件 myutils，持續改版	使用 pip install -e . 於開發環境，發佈至內部 PyPI 後改為 pip install myutils==x.y.z
跨平台腳本	在 Windows、macOS、Linux 上皆可執行	使用 python -m pip 呼叫 pip，確保指向正確的 Python 直譯器

---

總結

• pip 是 Python 生態系統的核心套件管理工具，掌握其基本指令與進階技巧，是開發者不可或缺的能力。
• 虛擬環境 能有效隔離相依，防止全域衝突；requirements.txt 則提供版本鎖定與環境可重現性。
• 在實務上，從 資料分析、Web 開發 到 CI/CD，皆依賴 pip 來確保套件一致性與快速部署。
• 避免常見陷阱（全域安裝、版本不一致、相依衝突），並遵循 升級 pip、使用虛擬環境、鎖定版本 的最佳實踐，能讓你的 Python 專案更穩定、可維護。

最後提醒：每次開始新專案時，先建立虛擬環境、寫好 requirements.txt，並在 CI 中加入 pip install -r requirements.txt 步驟，這樣才能真正發揮 pip 的威力，讓開發與部署流程順暢無阻。祝你玩得開心，寫出更好、更可靠的 Python 程式！