Python包本地运行与pip安装后导入路径不一致的解决方法

核心问题根源 #

本地直接运行包目录时，Python会将当前执行目录（即src/pkg）加入sys.path，此时同目录模块可直接导入；但pip安装后，包会被放到site-packages下，模块属于包的命名空间，必须用绝对导入才能找到。两种场景下sys.path的差异导致导入冲突。

可行解决方案 #

方案1：统一绝对导入 + 本地运行时自动添加src路径 #

在__main__.py开头加入一段代码，动态将src目录加入sys.path，确保本地运行时能识别包的命名空间：

import sys
from pathlib import Path

# 获取当前脚本所在目录的父目录（即src目录）
src_path = Path(__file__).resolve().parent.parent
if str(src_path) not in sys.path:
    sys.path.insert(0, str(src_path))

# 统一使用绝对导入
from pkg.assets import your_function  # 替换为实际的包名和模块内容

• 优点：导入逻辑统一，无需修改运行命令
• 缺点：需要额外的路径处理代码

方案2：使用开发模式安装本地包 #

直接通过pip的开发模式安装本地包，让本地运行环境与pip安装后的环境完全一致：

1. 进入example_project目录
2. 执行命令：

pip install -e .

安装后，无论本地运行python src/pkg User还是执行example User（需在pyproject.toml中配置console_scripts），都可以使用统一的绝对导入（如from pkg.assets import...）。

• 优点：完全遵循Python包开发规范，无导入兼容问题
• 缺点：需要执行一次开发安装命令

方案3：try-except兼容两种导入方式 #

通过捕获导入异常，自动适配本地和安装后的场景：

try:
    # 本地直接运行时的导入逻辑（同目录直接导入）
    from assets import your_function
except ImportError:
    # 安装后的绝对导入逻辑
    from pkg.assets import your_function

• 优点：无需修改运行命令或额外配置
• 缺点：代码略显hack，若包结构调整可能需要同步修改导入逻辑

方案4：通过-m参数以模块方式运行本地代码 #

进入example_project目录，使用模块方式运行包：

python -m src.pkg User

此时Python会将example_project目录加入sys.path，可以直接使用绝对导入from pkg.assets import...，同时pip安装后也能正常使用该导入方式。

• 优点：无需修改代码，符合Python模块运行规范
• 缺点：本地运行命令需调整为模块方式

推荐方案 #

优先选择方案2（开发模式安装）或方案4（模块方式运行），这两种方式更符合Python包的设计原则，避免引入额外的路径处理代码。

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