Python导入模块时sys.path.append相对路径不生效问题如何解决？

你遇到的问题本质是Python解析相对路径时，默认基于运行脚本时的当前工作目录（CWD），而非代码文件自身所在目录。当你在根目录执行python main.py时，CWD为main.py所在的根目录，因此module.py中写的相对路径会默认基于根目录解析，才会出现只有从main.py层级写路径才生效的情况。

解决方案 #

1. 基于模块自身__file__属性拼接路径（最快捷） #

每个Python模块的内置变量__file__会存储该模块文件的绝对路径，基于这个值拼接目标路径，可以保证路径永远和模块自身位置绑定，不受上层导入脚本的影响。
module.py代码修改示例：

import sys
import os

# 获取当前module.py文件所在的目录绝对路径
MODULE_PATH = os.path.dirname(os.path.abspath(__file__))
# 拼接module.py到目标包的相对路径，比如目标包在module.py同层级的utils目录下
sys.path.append(os.path.join(MODULE_PATH, "./utils"))
# 也可以拼接任意相对于module.py位置的路径，比如上层目录的其他包
sys.path.append(os.path.join(MODULE_PATH, "../other_package"))

2. 配置PYTHONPATH环境变量（更规范的小项目方案） #

将项目根目录的绝对路径添加到系统的PYTHONPATH环境变量中，Python导入模块时会自动在PYTHONPATH下的目录搜索，无需在代码中随处修改sys.path。
配置完成后你可以直接使用基于项目根目录的绝对导入：

• main.py中直接写import folder.module，无需先append folder到sys.path
• module.py中导入其他模块时直接写基于项目根的导入路径，比如import folder.utils.xxx

3. 打包为可安装模块（适合长期维护的正式项目） #

在项目根目录编写pyproject.toml或setup.py配置文件，将项目作为包安装到当前Python环境的site-packages中，所有模块的导入路径会全局生效，完全不需要手动修改sys.path。

避坑提示 #

• 除非临时测试，否则不要用相对路径修改sys.path，跨层级导入时极容易出现路径混乱问题
• 执行Python脚本时尽量从项目根目录启动，避免CWD和项目根目录不一致导致的导入异常
• 优先使用Python原生的导入规则，减少手动修改sys.path的场景

内容的提问来源于stack exchange，提问作者Arthur-Zakv