PyMuPDF（fitz）无法被PyCharm及pipreqs同步至requirements.txt的技术问询

一、代码层面的适配方案（无需修改PyMuPDF源码） #

这些方法能让PyCharm、pipreqs等工具正确识别依赖，避免误删：

• 显式声明依赖关联：在导入fitz的代码上方加注释，明确告知工具该导入对应PyMuPDF包：

  # requirements: PyMuPDF
  import fitz
  

  包括PyCharm在内的多数依赖扫描工具会识别这类注释格式。
• 添加冗余导入声明：在项目入口文件（比如Flask的app.py）中添加一行仅用于依赖检测的导入：

  import PyMuPDF  # 仅为让工具识别依赖，实际业务逻辑用fitz
  import fitz
  

  该导入不影响运行，但能让工具捕捉到PyMuPDF这个包依赖，手动添加到requirements.txt后，PyCharm也不会再出现警告。
• 指定pipreqs强制包含包：运行pipreqs时通过参数强制指定要包含的包：

  pipreqs --include PyMuPDF ./
  

二、PyMuPDF源码层面的修改（适合愿意调整包源码的场景） #

问题根源是PyMuPDF的包名是PyMuPDF，但对外暴露的导入模块是fitz，工具无法自动关联两者。要从根源解决，可修改包结构：

• 添加PyMuPDF模块重定向：在PyMuPDF的安装目录下创建PyMuPDF/__init__.py文件，内容如下：

  from fitz import *
  __version__ = fitz.__version__
  

  这样用户既可以用import PyMuPDF替代import fitz让工具直接识别包名，也能保留原有import fitz的兼容性。
• 修改包的构建配置：在PyMuPDF的setup.py（或pyproject.toml）中，将fitz和PyMuPDF都声明为包，明确模块与包的归属关系：

  # setup.py示例片段
  setup(
      name="PyMuPDF",
      packages=["fitz", "PyMuPDF"],
      # 其他原有配置...
  )
  

  这样包索引和依赖检测工具就能明确fitz模块属于PyMuPDF包。

内容的提问来源于stack exchange，提问作者DFW