Python 中如何导入其他目录（文件夹）里的模块？

推荐排序：一、把项目组织成包（各目录加 __init__.py），用包路径导入；二、pip install -e . 安装项目本身；三、临时方案用 sys.path.append()；四、按文件路径导入用 importlib.util。

目录结构示例

project/
├── main.py
├── utils/
│   ├── __init__.py
│   └── helpers.py
└── scripts/
    └── tool.py

方案一：包导入（推荐）

各目录加 __init__.py 后，从项目根目录运行，用点号路径导入：

# main.py
from utils.helpers import my_function

配合 python -m 运行：

python -m scripts.tool

方案二：pip install -e .

有 pyproject.toml 的项目执行可编辑安装，之后任何位置都能 import 项目包。

方案三：sys.path.append（临时方案）

import sys
sys.path.append("/path/to/utils")

import helpers

缺点：硬编码路径、依赖运行目录，只建议快速脚本用。

方案四：importlib 按路径导入

import importlib.util

spec = importlib.util.spec_from_file_location("helpers", "/path/to/utils/helpers.py")
helpers = importlib.util.module_from_spec(spec)
spec.loader.exec_module(helpers)

helpers.my_function()

适合插件系统——路径在运行时动态确定。

常见问题（FAQ）

Q：IDE 里能导入，命令行报错 ModuleNotFoundError？
A：IDE 自动把项目根目录加入了 sys.path。命令行从项目根目录运行，或用 python -m。

Q：相对导入 from ..utils import x 报错？
A：相对导入只在包内有效，直接运行文件时 __package__ 为空。改用绝对导入或 python -m 方式运行。

Q：导入同名模块冲突了？
A：检查 sys.path 中是否有多个同名模块，print(module.__file__) 看实际加载的是哪个。