使用pyproject.toml构建自定义包后无法导入函数的问题排查

一、pip安装到全局环境的问题 #

• 虚拟环境未激活：执行pip install .前必须激活venv。Windows运行venv\Scripts\activate，Linux/macOS运行source venv/bin/activate，激活后命令行前缀会显示(venv)。
• pip调用路径错误：即使激活虚拟环境，直接用pip可能调用全局版本。改用python -m pip install .，强制使用虚拟环境内的pip工具。

二、无法导入pkg.test_main及子包的问题 #

1. 包模块未在__init__.py中导出 #

默认情况下，import pkg后无法直接访问同级的test_main.py，需要在src/pkg/__init__.py中显式导入：

from . import test_main
from . import sub_pkg_1

这样导入pkg后，就能通过pkg.test_main、pkg.sub_pkg_1访问对应模块和子包。

2. 确认安装包的完整性 #

你的pyproject.toml中[tool.setuptools.packages.find]配置会自动收集src下所有带__init__.py的子包，但要确保：

• test_main.py确实在src/pkg目录下；
• 安装时没有报错，虚拟环境的site-packages中能找到完整的pkg目录（包含test_main.py、sub_pkg_1等）。

3. 确保IDLE使用虚拟环境的Python #

如果IDLE加载的是全局Python，自然会读取全局site-packages的pkg。要启动虚拟环境对应的IDLE：

• Windows：打开命令行激活venv后，运行python -m idlelib.idle
• Linux/macOS：激活venv后，运行python -m idlelib.idle

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