pipenv虚拟环境运行FastAPI应用时提示pdfkit模块未找到

首先定位核心矛盾：pip freeze能查到pdfkit但运行时提示模块不存在，90%以上的原因是启动FastAPI服务的Python解释器和你装pdfkit的虚拟环境不是同一个，按以下顺序排查即可：

• 第一步：确认uvicorn调用来源
  激活pipenv虚拟环境后，执行以下命令查看当前调用的uvicorn路径：

  • Mac/Linux系统：which uvicorn
  • Windows系统：where uvicorn
    如果返回的路径不在当前项目的pipenv虚拟环境目录下，说明你调用的是全局安装的uvicorn，用的是全局Python环境——全局环境没装pdfkit，自然报模块不存在。
    临时修复直接用pipenv强制调用环境内命令启动：

  pipenv run uvicorn backend:app --reload
  

  永久修复需要把uvicorn安装到当前pipenv环境内，在项目根目录执行：

  pipenv install uvicorn
  

  安装完成后再执行路径查询命令，确认uvicorn指向虚拟环境内的路径，之后直接用原启动命令即可。

• 第二步：验证当前环境pdfkit可用性
  激活虚拟环境后执行以下命令，直接测试当前Python解释器能不能正常导入pdfkit：

  python -c "import pdfkit; print(pdfkit.__file__)"
  

  如果这条命令直接报错，说明你之前安装pdfkit时没有在项目根目录执行，包装到了其他虚拟环境，重新在当前项目根目录执行pipenv install pdfkit即可。
  如果这条命令能正常输出pdfkit的安装路径，说明环境本身没问题，回到第一步检查uvicorn的调用来源即可。

• 第三步：排查同名文件冲突
  检查项目根目录下是否存在名为pdfkit.py的文件，或是名为pdfkit的文件夹，如果有就重命名——Python导入包时会优先读取当前项目目录下的同名文件/文件夹，覆盖第三方包的导入逻辑，直接导致模块找不到的报错。

补充：解决模块导入问题后，你大概率会遇到下一个报错：pdfkit是wkhtmltopdf的Python封装层，本身不包含PDF渲染的二进制程序，需要额外安装wkhtmltopdf才能正常生成PDF：

• Mac：执行brew install wkhtmltopdf
• Ubuntu/Debian：执行sudo apt install wkhtmltopdf
• Windows：下载对应安装包安装后，把wkhtmltopdf的bin目录添加到系统环境变量PATH即可。

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