自定义Python模块jbpy已安装但导入报ModuleNotFoundError求助

开发了名为jbpy的自定义Python模块，采用setuptools与pyproject.toml作为构建系统。在Ubuntu 24.04及Windows 11的WSL环境中，模块可正常构建，通过pip安装wheel文件后，pip显示安装成功，且安装目录位于Python的包搜索路径中，但执行import jbpy.logging时抛出ModuleNotFoundError: No module named 'jbpy'错误。已确认测试脚本的shebang与命令行调用的python3一致，尝试root权限全局安装问题仍未解决。

构建与安装命令 #

构建 #

python3 -m build

安装 #

python3 -m pip install dist/jbpy-0.0.2.9-py3-none-any.whl

错误信息 #

$ ./importtest.py 
Traceback (most recent call last):
  File "/home/jbang/development/projects/jbpy/test/./importtest.py", line 8, in <module>
    import jbpy.logging
ModuleNotFoundError: No module named 'jbpy'

Python路径配置 #

sys.executable='/usr/bin/python3'

sys.path = [
    '/home/jbang/development/projects/jbpy/test',
    '/usr/lib/python312.zip',
    '/usr/lib/python3.12',
    '/usr/lib/python3.12/lib-dynload',
    '/home/jbang/.local/lib/python3.12/site-packages',
    '/usr/local/lib/python3.12/dist-packages',
    '/usr/lib/python3/dist-packages',
    '/usr/lib/python3.12/dist-packages'
]

sysconfig.get_default_scheme()='posix_local'
sysconfig.get_preferred_scheme("prefix")='posix_local'
sysconfig.get_preferred_scheme("home")='posix_home'
sysconfig.get_preferred_scheme("user")='posix_user'

sysconfig.get_paths('posix_local') = {
    'stdlib'      : '/usr/lib/python3.12',
    'platstdlib'  : '/usr/lib/python3.12',
    'purelib'     : '/usr/local/lib/python3.12/dist-packages',
    'platlib'     : '/usr/local/lib/python3.12/dist-packages',
    'include'     : '/usr/include/python3.12',
    'platinclude' : '/usr/include/python3.12',
    'scripts'     : '/usr/local/bin',
    'data'        : '/usr/local'
}
sysconfig.get_paths('posix_home') = {
    'stdlib'      : '/usr/lib/python',
    'platstdlib'  : '/usr/lib/python',
    'purelib'     : '/usr/lib/python',
    'platlib'     : '/usr/lib/python',
    'include'     : '/usr/include/python',
    'platinclude' : '/usr/include/python',
    'scripts'     : '/usr/bin',
    'data'        : '/usr'
}
sysconfig.get_paths('posix_user') = {
    'stdlib'     : '/home/jbang/.local/lib/python3.12',
    'platstdlib' : '/home/jbang/.local/lib/python3.12',
    'purelib'    : '/home/jbang/.local/lib/python3.12/site-packages',
    'platlib'    : '/home/jbang/.local/lib/python3.12/site-packages',
    'include'    : '/home/jbang/.local/include/python3.12',
    'scripts'    : '/home/jbang/.local/bin',
    'data'       : '/home/jbang/.local'
}

sysconfig.get_python_version()='3.12'
sysconfig.get_platform()='linux-x86_64'
os.name='posix'
sysconfig.get_path('stdlib')     = '/usr/lib/python3.12'
sysconfig.get_path('platstdlib') = '/usr/lib/python3.12'
sysconfig.get_path('purelib')    = '/usr/local/lib/python3.12/dist-packages'
sysconfig.get_path('platlib')    = '/usr/local/lib/python3.12/dist-packages'
sysconfig.get_path('include')    = '/usr/include/python3.12'
sysconfig.get_path('scripts')    = '/usr/local/bin'
sysconfig.get_path('data')       = '/usr/local'

pyproject.toml内容 #

[build-system]
requires = ["setuptools >= 77.0.3"]
build-backend = "setuptools.build_meta"

[project]
name = "jbpy"
version = "0.0.2.9"
authors = [{name = "Jens Bang", email = "xxxx@xxxx.xx"}]
description = "A package with utility functions to make my Python life easier."
readme = "README.md"
requires-python = ">=3.6"
license = "BSD-3-Clause"
classifiers = [
    "Programming Language :: Python :: 3",
]

[tool.setuptools.packages.find]
where = ["src"]  # list of folders that contain the packages (["."] by default)
include = ["argparse*", "logging*", "json*"]  # package names should match these glob patterns (["*"] by default)
exclude = ["__*"]  # exclude packages matching these glob patterns (empty by default)
namespaces = false  # to disable scanning PEP 420 namespaces (true by default)

文件结构 #

.
├── changelog.md
├── dist/
├── generate_package.sh
├── install_package.sh
├── pyproject.toml
├── README.md
├── requirements.txt
├── src
│   ├── argparse.py
│   ├── general.py
│   ├── __init__.py
│   ├── jbpy.egg-info/
│   ├── json.py
│   └── logging.py
├── test/
└── venv/

问题根源在于包结构与配置不匹配，导致setuptools没有正确识别并打包jbpy模块：

1. 修正文件结构
   Python要求包必须以文件夹形式存在，当前src下直接存放模块文件的方式无法被识别为jbpy包。需要在src下创建jbpy子目录，将所有模块文件和__init__.py移入其中：

   .
   ├── ...
   ├── src
   │   └── jbpy
   │       ├── argparse.py
   │       ├── general.py
   │       ├── __init__.py
   │       ├── json.py
   │       └── logging.py
   ├── ...
   

2. 调整pyproject.toml配置
   [tool.setuptools.packages.find]的include参数需要匹配jbpy包名，而不是单个模块名。修改为：

   [tool.setuptools.packages.find]
   where = ["src"]
   include = ["jbpy*"]
   exclude = ["__*"]
   namespaces = false
   

3. 重新构建验证
   执行python3 -m build重新构建包，再用pip install安装新生成的wheel文件。最后运行以下命令确认安装：

   python3 -c "import jbpy; print(jbpy.__file__)"
   

   若输出正确的包路径，说明安装成功，此时import jbpy.logging即可正常执行。

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