Python同级目录下怎么导入另一个py文件

一、同级文件导入的基本写法

假设我们有一个正在开发的工程文件夹，里面包含两个处于同一层级的 Python 源代码文件：一个是提供工具函数的 utils.py，另一个是负责主执行逻辑的 main.py。

在 Python 语法中，同级文件的导入主要有两种等效且规范的写法：

• 全模块导入：import utils。调用内部函数时需加上模块前缀，如 utils.add_numbers(1, 2)。这种方式能清晰辨识函数来源，避免命名冲突。
• 指定对象导入：from utils import add_numbers。调用时直接执行 add_numbers(1, 2)，代码表达更为简洁。

图1：同一目录下 utils.py 与 main.py 的文件位置及直接调用示意

二、完整操作与代码示例

为了让验证过程确定无误，下面给出一组完整的可运行示例代码，读者可以在本地任意空文件夹中建立测试。

1. 编写被调用的同级模块 utils.py

# utils.py
def calculate(a, b):
    """返回两数相加的结果"""
    return a + b

APP_NAME = "数据处理助手"

2. 编写执行脚本 main.py 并导入同级模块

# main.py
import utils
from utils import calculate

print(f"当前工具名称: {utils.APP_NAME}")
result = calculate(100, 250)
print(f"运算结果: {result}")

3. 终端进入目录并执行验证

在命令行终端中，进入存放这两个文件的目录并运行 main.py：

cd /path/to/my_project
python main.py

控制台将正确输出：

当前工具名称: 数据处理助手
运算结果: 350

图2：同级 Python 模块创建、编写、定位与执行的标准化步骤

三、核心机制：Python 是如何找到同级文件的

为什么仅仅写一个模块名，Python 就能精准找到旁边的 utils.py？这背后依赖于解释器的 sys.path 模块查找列表。

当我们在终端直接运行 python main.py 时，Python 会在启动的瞬间进行环境初始化，并将 正在执行的主脚本所在目录的绝对路径 自动插入到 sys.path 的第一个位置（即 sys.path[0]）。

随后，当代码运行到 import utils 时，Python 按照以下优先级顺序在 sys.path 中逐项查找同名文件：

1. sys.path[0]（当前运行脚本所在的同级目录）：首个查找点，直接匹配到 utils.py，立即加载。
2. Python 标准库路径：若首个位置未找到，继续查找 Python 内置模块（如 json, os, math）。
3. 第三方安装包目录（site-packages）：通过 pip 安装的第三方包存放路径。

图3：Python 解释器优先从 sys.path[0] 查找同级文件的检索机制

四、常见报错场景与排查解决方法

1. 跨目录调用导致的 ModuleNotFoundError

这是同级导入中最常见的坑。假设终端当前在父级目录 workspace 下，直接运行子目录中的脚本：

# 错误执行方式
cd /workspace
python my_project/main.py

此时如果 main.py 内部写了 import utils，可能触发 ModuleNotFoundError: No module named 'utils'。为了使脚本在任何执行路径下都能无条件导入同级文件，可以在 main.py 最顶部加入稳健的目录注入代码：

# 在 main.py 顶部添加保证路径
import sys
import os

current_dir = os.path.dirname(os.path.abspath(__file__))
if current_dir not in sys.path:
    sys.path.insert(0, current_dir)

import utils  # 此时无论在哪里执行 python 命令，都能确保找到 utils

2. 误用相对导入点号（.）引发的 ImportError

很多开发者从包设计教程中看到 from . import utils，便尝试在同级脚本中照搬。然而直接执行该文件时会抛出异常：

ImportError: attempted relative import with no known parent package

原因：点号（.）属于显式相对导入，其成立的前提是当前文件必须作为某个“已知父级包（Package）”的一部分被模块化调用。直接以 python main.py 形式作为主程序入口运行时，当前模块的 __name__ 会被设置为 '__main__'，并没有所属包上下文，因此相对导入必定失败。同级主脚本必须使用直接导入语法 import utils。

3. 文件名与内置库或关键字冲突

如果你将同级文件命名为 test.py、math.py、json.py 或 email.py，在导入时极易出现循环导入或覆盖标准库的诡异现象。请务必使用明确的业务名称，避免重名。

图4：同级导入中相对导入报错、后缀误区与路径防护方案总结

五、操作注意事项与核心总结