Python 專案若只想產生「程式實際 import 到的 Library 列表」，我會優先用 `pipreqs` 產生 `requirements.txt`，而不是直接把整個環境用 `pip freeze` 匯出。`pip freeze` 適合保存目前環境快照；`pipreqs` 則會掃描專案程式碼中的 import，較適合從既有專案整理出乾淨的依賴清單。
為什麼 `pip freeze` 會產生過多套件？
`pip freeze` 會輸出目前 Python 環境中已安裝的套件，而不是判斷專案程式碼實際使用哪些套件。共用環境、長期開發環境或曾安裝 `.whl` 的環境，常會產生過多或帶本機路徑的清單。
傳統方式如下：
```bash
pip freeze > requirements.txt
```
這個指令很方便，但輸出來源是目前 Python environment 裡的 installed packages。pip 官方文件也把 `pip freeze` 定義為輸出已安裝套件的 requirements 格式，並說明可再用 `pip install -r requirements.txt` 重建另一個環境（pip documentation，存取日期：2026-08-28）。
問題是，開發機上的 environment 不一定只服務單一專案。若我在同一個環境測試過其他工具、安裝過臨時套件，`pip freeze` 也會一起列出，導致新的環境被塞進不必要的 library。
為什麼 `.whl` 或本機路徑會讓 requirements.txt 難重建？
`requirements.txt` 可以描述套件名稱、版本、URL、本機路徑與 wheel 檔案。這種彈性很有用，但若檔案帶入開發機的 `file://` 絕對路徑，其他機器通常無法照原樣安裝。
我在整理環境時遇過類似這種輸出：
```text
jsonschema @ file:///home/conda/feedstock_root/build_artifacts/jsonschema-meta_1669810440410/work
```
這種清單拿去建立新環境時很容易失敗，因為 `/home/conda/feedstock_root/...` 是特定建置環境或本機路徑，不是團隊其他人也能存取的套件來源。pip requirements file format 支援 local distribution paths、local project paths 與 URLs，但這也代表清單可能混入不可移植的位置（pip documentation，存取日期：2026-08-28）。
我的判斷是：如果目標是「重現整個環境」，`pip freeze` 很合理；如果目標是「回推這個專案真正用到哪些第三方套件」，`pip freeze` 就常常太粗。
pipreqs 如何生成只包含專案使用的 Library 列表？
`pipreqs` 會掃描指定目錄中的 Python import，並依照 import 結果產生 `requirements.txt`。這種方式比較像從程式碼反推專案依賴，適合整理舊專案或清掉環境漂移造成的雜訊。
我推薦的套件是 `pipreqs`。安裝與基本使用方式如下：
```bash
pip install pipreqs
pipreqs . --force
```
`pipreqs . --force` 會掃描目前目錄，並覆蓋既有的 `requirements.txt`。pipreqs 的 PyPI 頁面說明它是依據 project imports 產生 requirements.txt 的工具，常用參數也包含 `--force`、`--savepath`、`--diff`、`--clean`、`--print` 與 `--scan-notebooks`（PyPI，存取日期：2026-08-28）。
我通常會在專案根目錄執行這個流程，原因是根目錄最容易涵蓋 `src/`、scripts、notebooks 或其他 Python 模組。如果專案有測試資料、暫存資料夾或 vendor code，再用 `--ignore` 排除不該掃描的目錄。
`pip freeze` 和 `pipreqs` 應該怎麼選？
`pip freeze` 適合保存當下環境狀態，`pipreqs` 適合整理專案實際 import 的直接依賴。兩者不是互相取代，而是回答不同問題。
| 工具 | 回答的問題 | 適合情境 | 主要風險 |
|---|---|---|---|
| `pip freeze` | 目前環境安裝了什麼？ | 保存環境快照、同環境重建、部署前鎖定版本 | 可能包含未使用套件、本機路徑或過度膨脹的間接依賴 |
| `pipreqs` | 專案程式碼 import 了什麼？ | 既有專案補 requirements、清理依賴清單、避免環境雜訊 | 動態 import、外部 plugin、命令列工具依賴可能需要人工補上 |
資訊增益：我會把 `pipreqs` 產出的檔案當成第一版，再用實際測試修正。尤其是 Django settings、Celery worker、Jupyter notebook 或 plugin 型架構，部分依賴不一定會在一般 `.py` import 掃描中完整浮現。
pipreqs 常用選項有哪些？
`pipreqs` 的常用選項集中在輸出位置、覆蓋既有檔案、比對差異與除錯。整理舊專案時，我會先用 `--print` 或 `--diff` 看結果，再決定是否覆蓋 requirements.txt。
常用選項如下：
| 選項 | 用途 | 我會在什麼時候用 |
|---|---|---|
| `--savepath` | 指定生成檔案的保存路徑 | 想輸出成 `requirements.generated.txt` 先審查 |
| `--force` | 強制覆蓋既有 `requirements.txt` | 已確認要直接更新專案依賴清單 |
| `--diff` | 比較生成清單與既有 requirements | 想知道目前檔案多了或少了哪些項目 |
| `--clean` | 移除既有 requirements 中未被 import 的項目 | 想清理舊清單，但仍需人工 review |
| `--debug` | 輸出更多掃描與對應資訊 | 掃描結果少於預期時排查 |
| `--ignore` | 忽略指定目錄 | 排除 `venv`、`dist`、測試輸出或第三方程式碼 |
| `--scan-notebooks` | 掃描 Jupyter notebook imports | 專案依賴散在 `.ipynb` 時使用 |
較保守的流程可以這樣跑：
```bash
pipreqs . --print
pipreqs . --diff requirements.txt
pipreqs . --savepath requirements.generated.txt
```
確認結果合理後，再覆蓋正式檔案：
```bash
pipreqs . --force
```
我實際整理 Python 專案依賴時會怎麼做？
整理 Python 專案依賴時，我會先讓 `pipreqs` 產生乾淨清單，再用測試與啟動流程補齊掃描不到的依賴。這樣可以避免把整個開發環境的歷史包袱寫進專案。
我的流程通常是：
- 進入專案根目錄，確認目前使用的是專案專屬 virtual environment。
- 執行 `pipreqs . --print` 先看掃描結果。
- 若有不該掃描的目錄，加上 `--ignore venv,dist,build`。
- 用 `pipreqs . --savepath requirements.generated.txt` 產生可審查版本。
- 比對既有檔案：`pipreqs . --diff requirements.txt`。
- 確認後執行 `pipreqs . --force` 更新 `requirements.txt`。
- 建立乾淨環境，執行 `pip install -r requirements.txt`。
- 跑測試、啟動服務、執行主要 batch 或 notebook，補上掃描不到但實際需要的依賴。
這個流程保留了原本最重要的指令，同時多加一個 review 階段。依賴檔一旦進 Git，就會影響團隊每個人的安裝流程；先把結果看過一遍，比事後追查「為什麼新環境不能跑」便宜很多。
延伸閱讀
- Angular NPM 與 package.json 設定教學
- Git 版本控管入門筆記：從 SVN 轉換到分散式開發
- 使用 Conda 管理 Python 版本與函式庫
- Docker 刪除所有 tag 為 None 的 image：清理 dangling images 指令
- 使用 PM2 管理 Node.js 伺服器教學
常見問題
Python 專案依賴清單的常見問題，通常集中在 `pip freeze` 是否足夠、`pipreqs` 是否會漏套件，以及產出的 `requirements.txt` 能不能直接部署。以下答案可作為整理依賴前的檢查點。
pipreqs 會取代 pip freeze 嗎？
`pipreqs` 不完全取代 `pip freeze`。`pipreqs` 適合從程式碼 import 產生直接依賴清單；`pip freeze` 適合保存目前環境的完整安裝快照。若要部署可重現環境，仍要搭配測試與版本鎖定策略。
為什麼 pip freeze 產出的 requirements.txt 很長？
`pip freeze` 會列出目前環境已安裝的套件，不會判斷專案是否真的 import 那些套件。共用 virtual environment、長期開發機或資料科學環境，很容易累積很多與目前專案無關的 library。
pipreqs 掃描不到某些套件怎麼辦？
`pipreqs` 主要根據 import 靜態掃描，動態載入、plugin、CLI-only dependency 或設定檔中的依賴可能需要人工補上。遇到這種狀況，我會建立乾淨環境安裝產出的 `requirements.txt`，再用測試和啟動流程補齊缺口。
requirements.txt 裡出現 file:/// 路徑可以提交嗎？
通常不建議直接提交帶有本機絕對路徑的 `file:///` 項目，因為團隊其他人的電腦或部署環境多半沒有同一個路徑。若真的需要安裝內部 wheel，建議改用可存取的套件倉庫、HTTPS 下載位置或清楚的建置流程。
pipreqs 產生的 requirements.txt 可以直接上 production 嗎？
不建議未測試就直接上 production。`pipreqs` 產生的是很好的起點，但正式部署前仍應在乾淨環境中安裝、跑測試、啟動主要服務，並確認版本釘選策略符合團隊需求。
Python 專案的 requirements.txt 應該放進 Git 嗎？
多數 Python 應用專案應該把 `requirements.txt` 或等價的依賴描述檔放進 Git。這樣團隊成員、CI 與部署環境才能用同一份清單建立環境，也能在 code review 時看見依賴變更。
參考資料
- pip documentation：pip freeze（存取日期：2026-08-28）
- pip documentation：Requirements File Format（存取日期：2026-08-28）
- PyPI：pipreqs（存取日期：2026-08-28）
- GitHub：bndr/pipreqs（存取日期：2026-08-28）
最後更新
本文最後更新於 2026-08-28。我當時的筆記發布於 2024-11-05，本文保留 `pip freeze > requirements.txt`、`pipreqs . --force`、`.whl`/`file://` 路徑問題與 pipreqs 常用選項，並補上 Answer Blocks、FAQ、參考資料與依賴整理流程。
關於作者 {#author}
Claire Chang ｜ 企業 AI 導入與流程轉型顧問。專注於 AI Agent 架構設計、ERP 系統整合與企業 AI 治理。
首次發布：2024-11-05