萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python 模組搜尋路徑機制與安裝方式完整指南

import 機制三步驟

  1. 尋找模組檔案:依 sys.path 順序搜尋
  2. 編譯為位元碼:生成 .pyc 快取 (__pycache__ 目錄)
  3. 執行模組程式碼:建立模組物件,註冊至 sys.modules

同一模組再次 import 直接從 sys.modules 取得,跳過上述三步。

模組搜尋路徑優先順序 (sys.path)

優先級來源說明範例
1腳本主目錄啟動腳本所在目錄 (互動模式為空字串 '')/home/user/project/
2PYTHONPATH 環境變數類似 PATH,多目錄用 : (Win ;) 分隔export PYTHONPATH=/opt/mylib:/home/user/lib
3標準庫目錄Python 安裝路徑下的 Lib//usr/lib/python3.11/
4.pth 檔案目錄site-packages 下的 .pth 內容 (每行一路徑)/usr/lib/python3.11/site-packages/easy-install.pth
5site-packages第三方套件安裝目錄/usr/lib/python3.11/site-packages/

動態修改 sys.path (臨時生效)


import sys
sys.path.append('/tmp/my_modules')  # 末尾新增
sys.path.insert(0, '/priority/path') # 優先搜尋
sys.path.remove('/tmp/my_modules')   # 移除

⚠️ 僅影響當前進程,退出即失效。

永久生效的四種安裝方式

1. 開發模式安裝 (推薦開發中套件)


cd /path/to/my_package  # 含 setup.py/pyproject.toml
pip install -e .        # 可編輯模式,原始碼修改即時生效

2. pip 安裝 (PyPI / 私有索引 / 本地檔案)


pip install requests                    # PyPI
pip install -i https://pypi.mycorp.com/simple mypkg  # 私有源
pip install ./dist/mypkg-1.0.tar.gz     # 本地 wheel/sdist
pip install git+https://github.com/user/repo.git@v1.2  # Git 存儲庫

3. 系統套件管理器 (Linux/macOS)


apt install python3-requests    # Debian/Ubuntu
dnf install python3-requests    # Fedora/RHEL
brew install python-requests    # macOS Homebrew

優點:系統級更新;缺點:版本較舊、可能衝突 virtualenv。

4. 手動放置 (不推薦,除非特殊需求)


# 將純 Python 模組複製到 site-packages
cp -r my_module /usr/lib/python3.11/site-packages/
# 或建立 .pth 檔指向原始碼目錄
echo "/home/user/my_project/src" > /usr/lib/python3.11/site-packages/my_project.pth

虛擬環境:隔離依賴的標準做法


# 建立
python -m venv .venv

# 啟動
source .venv/bin/activate      # Linux/macOS
.venv\Scripts\activate         # Windows CMD
.venv\Scripts\Activate.ps1     # PowerShell

# 環境內 pip 安裝僅影響該環境
pip install numpy pandas

常見問題排查

  1. ImportError: No module named 'xxx'
    • 確認虛擬環境已啟動
    • pip list 檢查是否安裝
    • python -c "import sys; print('\n'.join(sys.path)) 檢查路徑
  2. 版本衝突:使用 pip check 檢測,pip install --upgrade 或鎖定版本 requirements.txt
  3. 命名空間套件:多個套件共享同一頂層包名 (如 google.cloud.*),需確保皆為 namespace_packages 宣告
  4. C 擴充編譯失敗:安裝建構工具 (apt install python3-dev build-essential / Visual Studio Build Tools)

現代工具鏈建議

  • 依賴管理:poetry / pdm (取代 requirements.txt + pip)
  • 環境管理:pyenv + venv / conda / uv (極速新秀)
  • 鎖定檔:poetry.lock / pdm.lock / requirements.txt (pip-tools 編譯)

理解搜尋機制與善用虛擬環境,是 Python 專案穩定部署的基石。

copyright © 萬盛學電腦網 all rights reserved