Python 專案若只想產生「程式實際 import 到的 Library 列表」，我會優先用 pipreqs 產生 requirements.txt，而不是直接把整個環境用 pip freeze 匯出。pip freeze 適合保存目前環境快照；pipreqs 則會掃描專案程式碼中的 import，較適合從既有專案整理出乾淨的依賴清單。
為什麼 pip freeze 會產生過多套件？
pip freeze 會輸出目前 Python 環境中已安裝的套件，而不是判斷專案程式碼實際使用哪些套件。共用環境、長期開發環境或曾安裝 .whl 的環境，常會產生過多或帶本機路徑的清單。
傳統方式如下：
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:// 絕對路徑，其他機器通常無法照原樣安裝。
我在整理環境時遇過類似這種輸出：
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。安裝與基本使用方式如下：
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 時使用 |
較保守的流程可以這樣跑：
pipreqs . --print
pipreqs . --diff requirements.txt
pipreqs . --savepath requirements.generated.txt
確認結果合理後，再覆蓋正式檔案：
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，就會影響團隊每個人的安裝流程；先把結果看過一遍，比事後追查「為什麼新環境不能跑」便宜很多。
常見問題
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）
延伸閱讀
- 為每個 Python 專案建立獨立的虛擬環境：同樣聚焦 Python、requirements.txt，可接著比較不同情境的做法。
- 使用 Conda 管理 Python 版本與函式庫：同樣聚焦 Python，可接著比較不同情境的做法。
- PyCharm 是什麼？好用的 Python 開發環境（IDE）推薦指南：同樣聚焦 Python，可接著比較不同情境的做法。
最後更新
本文最後更新於 2026-08-28。我當時的筆記發布於 2024-11-05，本文保留 pip freeze > requirements.txt、pipreqs . --force、.whl/file:// 路徑問題與 pipreqs 常用選項，並補上 Answer Blocks、FAQ、參考資料與依賴整理流程。
關於作者
Claire Chang ｜ 企業 AI 導入與流程轉型顧問。專注於 AI Agent 架構設計、ERP 系統整合與企業 AI 治理。
首次發布：2024-11-05