目录

1. 什么是 pipreqs（以及为什么要用它）
2. 安装方法
3. 基本使用（命令示例与代码示例）
4. 常用参数详解（例：--use-local、--force、--encoding 等）
5. 与 pip freeze / 其它工具的对比（何时用哪一个）
6. 高级场景：Jupyter / 单文件

---

1. 什么是 pipreqs（以及为什么要用它）

pipreqs 会扫描指定目录下的 Python 源文件（.py）中的 import 语句，并根据这些导入项生成 requirements.txt。它不是把当前虚拟环境全部列出来（那是 pip freeze 的做法），而是基于代码实际引用的包来生成更“精简”的依赖清单。适合开源项目、分享代码或希望让 requirements.txt 更可读、更小众化的场景

---

2. 安装方法

# 推荐在虚拟环境中安装
# 安装pipreqs
pip install pipreqs

如果你使用的是支持 notebook 的扩展（例如生成 notebook 的依赖），也可以考虑 pipreqsnb（是 pipreqs 的一个 wrapper，支持 notebook）

---

3. 基本使用（命令示例与代码示例）

3.1 根目录生成 requirements.txt

# 在项目根目录执行，生成 requirements.txt（默认会写入当前目录）
pipreqs .

（命令等同于 pipreqs /path/to/project）

3.2 将结果输出到指定文件

# 指定保存路径（例如保存为 my_requirements.txt）
pipreqs /path/to/project --savepath /path/to/project/my_requirements.txt

3.3 强制覆盖已存在的 requirements.txt

# 如果已有 requirements.txt，使用 --force 覆盖
pipreqs . --force

3.4 仅打印到标准输出（不写文件）

pipreqs . --print

3.5 最小 Python 代码示例（在脚本中调用，示意）

# -*- coding: utf-8 -*-
# 演示：在 Python 脚本内调用 pipreqs 相应逻辑（一般推荐直接使用命令行）
import subprocess
# 通过子进程调用 pipreqs （实际项目中直接在 shell 使用更简单）
subprocess.run(["pipreqs", ".", "--force"])

---

4. 常用参数详解（选项说明）

下面列出最常用的参数（并说明场景）：

• --savepath <file>：把生成的依赖写到指定文件。适合多模块项目或自定义文件名。([PyPI][3])
• --force：覆盖已存在的 requirements.txt。用于自动化脚本。([PyPI][3])
• --encoding <charset>：指定读取源文件时使用的编码（例如处理含中文注释或非 UTF-8 的仓库）。([Qiita][4])
• --use-local：只使用本地已安装包信息而不访问 PyPI（用于离线或限制外网访问的环境）。这是 pipreqs 生态下的常见选项（或其 wrapper 中可用的选项）；在某些派生工具或 wrapper 中有更详细的支持。([Qiita][4])
• --pypi-server <url> 与 --proxy <url>：用于公司私有 PyPI 或通过代理访问。([Qiita][4])

（不同版本/衍生包参数名可能略有差异，使用前请查看你安装版本的 --help 输出。）

---

5. 与 pip freeze / 其它工具的对比（何时用哪一个）

• pipreqs：基于代码导入，生成精简的 requirements.txt，适合用于项目发布、代码分享和依赖审查。它不会把全环境中无关包列入清单
• pip freeze：基于当前环境，把所有安装包（包含其依赖）写出并带有精确版本号，适合复制环境
• 备选工具：pigar、pip-tools、poetry、pipenv 等，适合更复杂的依赖管理或锁定/解析策略

---

6. 高级场景与实践

6.1 支持 Jupyter Notebook

pipreqs 本身主要针对 .py 文件。若你项目大量使用 notebook，可使用 pipreqsnb（wrapper，能处理 .ipynb）来生成依赖列表

6.2 单文件或子目录

可以直接目标单一文件或指定子目录：

# 单个文件（部分 wrapper 支持）
pipreqs path/to/module.py --savepath reqs.txt

（注意：原始 pipreqs 对单文件支持情况视版本而定，若不支持请用 wrapper 或临时将其放入单一目录再执行）。

---

附录：实用命令速查表

# pipreqs 常用命令速查

# 安装
pip install pipreqs

# 在当前目录生成 requirements.txt（默认）
pipreqs .

# 指定保存路径
pipreqs /path/to/project --savepath /path/to/project/reqs.txt

# 强制覆盖已存在文件
pipreqs . --force

# 只打印输出（不写文件）
pipreqs . --print

# 如果使用 notebook wrapper（pipreqsnb）
pip install pipreqsnb
pipreqsnb /path/to/notebooks --savepath reqs.txt

---