sys.path 順序搜尋.pyc 快取 (__pycache__ 目錄)sys.modules同一模組再次 import 直接從 sys.modules 取得,跳過上述三步。
| 優先級 | 來源 | 說明 | 範例 |
|---|---|---|---|
| 1 | 腳本主目錄 | 啟動腳本所在目錄 (互動模式為空字串 '') | /home/user/project/ |
| 2 | PYTHONPATH 環境變數 | 類似 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 |
| 5 | site-packages | 第三方套件安裝目錄 | /usr/lib/python3.11/site-packages/ |
import sys
sys.path.append('/tmp/my_modules') # 末尾新增
sys.path.insert(0, '/priority/path') # 優先搜尋
sys.path.remove('/tmp/my_modules') # 移除
⚠️ 僅影響當前進程,退出即失效。
cd /path/to/my_package # 含 setup.py/pyproject.toml
pip install -e . # 可編輯模式,原始碼修改即時生效
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 存儲庫
apt install python3-requests # Debian/Ubuntu
dnf install python3-requests # Fedora/RHEL
brew install python-requests # macOS Homebrew
優點:系統級更新;缺點:版本較舊、可能衝突 virtualenv。
# 將純 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
pip list 檢查是否安裝python -c "import sys; print('\n'.join(sys.path)) 檢查路徑pip check 檢測,pip install --upgrade 或鎖定版本 requirements.txtgoogle.cloud.*),需確保皆為 namespace_packages 宣告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 專案穩定部署的基石。