Python项目Homebrew打包后运行报错：找不到src模块

我正在为一个通过LLM与man页面交互的Python项目创建Homebrew formula，对应的Ruby代码如下：

class Scanman < Formula
  include Language::Python::Virtualenv

  desc "Using LLMs to interact with man pages"
  url "https://github.com/nikhilkmr300/scanman/archive/refs/tags/1.0.1.tar.gz"
  sha256 "93658e02082e9045b8a49628e7eec2e9463cb72b0e0e9f5040ff5d69f0ba06c8"

  depends_on "python@3.11"

  def install
    virtualenv_install_with_resources
    bin.install "scanman"
  end

  test do
    # Simply run the program
    system "#{bin}/scanman"
  end
end

安装后运行scanman时，程序报错找不到src目录下的自定义模块：

ModuleNotFoundError: No module named 'src'

项目目录结构：

.
├── requirements.txt
├── scanman
├── scanman.rb
├── setup.py
└── src
    ├── __init__.py
    ├── cli.py
    ├── commands.py
    ├── manpage.py
    ├── rag.py
    └── state.py

补充说明：本地仓库内运行scanman完全正常；PyPI安装的第三方包能正常找到，但在/usr/local/Cellar/scanman/1.0.1/libexec/lib/python3.11/site-packages/目录下看不到src相关的模块文件。

问题根源 #

1. setup.py配置缺失：Homebrew的virtualenv_install_with_resources依赖setup.py完成Python包的安装，如果setup.py未正确配置打包src目录下的模块，Homebrew构建时不会将这些自定义代码安装到虚拟环境的site-packages目录，导致运行时找不到src模块。
2. 路径环境差异：本地运行时，项目根目录在Python的sys.path中，能直接读取同级的src目录；但Homebrew安装后，程序在虚拟环境中运行，sys.path仅包含虚拟环境的site-packages和系统路径，没有项目根目录，自然找不到未被安装的src模块。
3. 手动复制脚本的冲突：Formula里的bin.install "scanman"直接复制项目根目录的脚本到Homebrew的bin目录，但该脚本依赖本地src路径，未指向虚拟环境中已安装的包结构，进一步加剧了模块找不到的问题。

修复步骤 #

1. 修正setup.py配置 #

确保setup.py正确包含src目录下的模块，示例配置如下：

from setuptools import setup, find_packages

setup(
    name="scanman",
    version="1.0.1",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    # 配置命令行入口，让setuptools自动生成正确的可执行脚本
    entry_points={
        "console_scripts": [
            "scanman = src.cli:main", # 替换为你实际的入口函数路径
        ],
    },
    install_requires=[
        line.strip() for line in open("requirements.txt") if line.strip()
    ]
)

2. 调整Homebrew Formula #

移除手动复制脚本的代码，virtualenv_install_with_resources会自动处理setup.py中配置的entry_points，生成正确的可执行脚本并放到bin目录：

class Scanman < Formula
  include Language::Python::Virtualenv

  desc "使用LLM与man页面交互"
  url "https://github.com/nikhilkmr300/scanman/archive/refs/tags/1.0.1.tar.gz"
  sha256 "93658e02082e9045b8a49628e7eec2e9463cb72b0e0e9f5040ff5d69f0ba06c8"

  depends_on "python@3.11"

  def install
    virtualenv_install_with_resources
    # 移除 bin.install "scanman"，由virtualenv_install_with_resources自动处理脚本
  end

  test do
    system "#{bin}/scanman", "--help" # 用更有意义的测试命令，比如查看帮助
  end
end

3. 验证构建 #

重新构建并安装：

brew uninstall scanman
brew install --build-from-source ./scanman.rb

运行scanman即可正常找到src模块。

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