Python 引入 `.py` 文件，核心就是让解释器在模块搜索路径中找到目标文件，然后使用 `import` 或 `from ... import ...` 加载其中的代码。最常见的做法是把两个文件放在同一目录下，例如 `main.py` 和 `user.py`，在 `main.py` 中写 `import user`，再通过 `user.函数名()`、`user.变量名` 或 `user.类名` 使用内容。若文件不在同一目录，就需要按包结构导入，或者调整项目目录与运行方式，而不是随意修改环境变量。

很多“明明有这个文件却导入失败”的问题，并不是 Python 语法写错，而是文件所在位置、运行入口、包结构和模块搜索路径没有对齐。掌握这几层关系后，普通文件引入、跨目录引入、包内引入以及第三方库引入，都可以用同一套思路判断和处理。

## 一、同一目录下引入 py 文件，先掌握最基本的方式

假设项目目录如下：

`project/`

`├── main.py`

`└── user.py`

`user.py` 中有一个函数：

`def say_hello(name):`

`    return f"你好，{name}"`

那么在 `main.py` 中可以这样写：

`import user`

`message = user.say_hello("小李")`

`print(message)`

这里的 `user` 就是模块名，通常对应 `user.py` 文件名，但导入时不需要写 `.py` 后缀。调用其中的内容时，要通过模块名加点号访问，例如 `user.say_hello()`。

也可以只引入指定的函数：

`from user import say_hello`

`print(say_hello("小李"))`

还可以一次引入多个对象：

`from user import say_hello, UserInfo`

这种写法调用时更简洁，但在文件较大、变量名称较多时，容易看不出某个函数来自哪个模块。因此，项目代码中通常会根据场景选择写法：

| 写法 | 调用形式 | 适合场景 | 主要风险 |
|---|---|---|---|
| `import user` | `user.say_hello()` | 模块内容较多，来源需要清晰 | 调用时名称稍长 |
| `from user import say_hello` | `say_hello()` | 只使用少量明确对象 | 可能与本文件名称冲突 |
| `import user as u` | `u.say_hello()` | 模块名较长或需要统一别名 | 别名不清晰时增加理解成本 |
| `from user import *` | 直接使用所有公开对象 | 不建议用于正式项目 | 容易覆盖变量，来源不明确 |

`from user import *` 虽然可以使用，但不建议作为日常写法。一个模块里可能有多个变量、函数和类，全部导入后，当前文件很难判断某个名称来自哪里；如果两个模块中存在同名函数，后导入的内容还可能覆盖先导入的内容。

### 1. 引入模块和执行模块不是一回事

当执行 `import user` 时，Python 不只是读取函数定义，还会执行 `user.py` 顶层的代码。

例如 `user.py` 中有：

`print("user 模块被加载")`

当 `main.py` 执行 `import user` 时，这句话会运行一次。此后再次导入同一个模块，Python 通常会使用已经加载的模块，不会重复执行整个文件。

因此，建议把可复用的函数、类和常量放在模块顶层，把测试代码放到：

`if __name__ == "__main__":`

下面。

例如：

`def say_hello(name):`

`    return f"你好，{name}"`

`if __name__ == "__main__":`

`    print(say_hello("测试用户"))`

这样直接运行 `user.py` 时，会执行测试代码；但被其他文件引入时，只会加载函数定义，不会自动执行测试部分。这是 Python 文件既能独立运行、又能作为模块复用的基本结构。

### 2. 文件名不能随便取

目标文件名会直接影响导入结果。以下名称容易造成问题：

- 文件名包含空格、连字符或特殊符号；
- 文件名以数字开头；
- 文件名与标准库名称相同；
- 文件名与正在使用的第三方库名称相同；
- 文件名叫 `python.py`、`random.py`、`json.py` 等，可能遮蔽同名库。

例如你在项目中创建了一个 `random.py`，之后写 `import random`，Python 可能优先加载你的文件，而不是标准库中的 `random` 模块。代码表现异常时，往往很难从报错表面看出原因。

文件名最好使用小写字母、数字和下划线，例如 `user_service.py`、`data_parser.py`。同时，文件名要表达职责，避免把大量不相关的功能都塞进一个模块。

## 二、跨目录引入时，关键不是改路径，而是理解项目结构

当两个 `.py` 文件不在同一目录，不能简单认为“写出文件夹名称就一定能导入”。Python 能否找到模块，取决于模块所在目录是否在搜索路径中，以及当前项目是否按包的方式组织。

例如：

`project/`

`├── main.py`

`└── services/`

`    └── user_service.py`

如果 `services` 是一个包，可以在 `main.py` 中写：

`from services import user_service`

调用时：

`user_service.say_hello()`

也可以直接引入函数：

`from services.user_service import say_hello`

`print(say_hello("小李"))`

在较新的 Python 版本中，`services` 目录即使没有 `__init__.py`，在很多情况下也能作为命名空间包使用。但为了让项目结构更清晰、兼容不同运行环境，并明确表达“这是一个可导入的包”，通常仍建议在业务包目录中放置 `__init__.py`。

目录可以整理成：

`project/`

`├── main.py`

`└── services/`

`    ├── __init__.py`

`    └── user_service.py`

`__init__.py` 可以是空文件，也可以放置包初始化内容。它的重点不是必须写代码，而是让目录结构更明确。

### 1. 多级目录应该使用完整包路径

如果目录进一步变成：

`project/`

`├── main.py`

`└── app/`

`    ├── __init__.py`

`    └── services/`

`        ├── __init__.py`

`        └── user_service.py`

那么可以写：

`from app.services.user_service import say_hello`

这里的导入路径是从项目根目录开始计算的，而不是从目标文件所在位置随意计算。只要 `project` 是运行时可识别的项目根目录，这种写法就比较稳定。

常见错误是把文件路径直接写进 `import`：

`import app/services/user_service.py`

这不是 Python 的模块导入语法。Python 导入使用点号表示包层级，正确形式是：

`from app.services import user_service`

或者：

`from app.services.user_service import say_hello`

导入路径表达的是模块名称，不是操作系统文件路径。Windows 下的反斜杠、Linux 下的斜杠，都不应直接写进模块导入语句。

### 2. 同一项目中推荐使用绝对导入

所谓绝对导入，就是从项目的顶层包开始写完整路径，例如：

`from app.services.user_service import say_hello`

这种方式能够直接看出模块来源，适合业务项目、接口服务和多人协作代码。

相对导入则使用点号表示当前包或上级包，例如在 `app/controllers/user_controller.py` 中：

`from ..services.user_service import say_hello`

其中一个点表示当前包层级，两个点表示上一级包。相对导入适合包内部模块之间的引用，但不能脱离包结构随意运行。

如果一个文件既要被当作包模块导入，又经常被直接双击或直接执行，相对导入可能出现错误。更稳妥的做法是明确项目入口，让业务文件作为模块运行，而不是把每个文件都当成独立脚本执行。

## 三、为什么会出现 ModuleNotFoundError，应该按顺序排查

`ModuleNotFoundError` 是导入问题中最常见的报错。它通常表示 Python 在当前模块搜索路径中没有找到目标模块，但不一定代表目标文件真的不存在。

排查时不要直接复制网上的路径修改方案，建议按照“文件名—目录结构—运行位置—导入写法”的顺序检查。

### 1. 先确认文件名和导入名一致

如果文件叫 `user_service.py`，导入时应写：

`import user_service`

不能写成：

`import user-service`

也不能写成：

`import user_service.py`

如果文件名大小写不同，在部分操作系统中可能暂时不报错，但部署到区分大小写的环境后就会失败。因此，导入名称和文件名称应保持完全一致。

### 2. 再确认运行入口在哪里

下面两种启动方式，可能导致不同的导入结果：

`python main.py`

`python -m app.main`

如果项目结构依赖包路径，使用 `python -m app.main` 往往更符合包的运行方式。它会把项目根目录作为模块环境的一部分，使包内绝对导入和相对导入更容易保持一致。

例如：

`project/`

`└── app/`

`    ├── __init__.py`

`    └── main.py`

在项目根目录执行：

`python -m app.main`

通常比进入 `app` 目录后执行：

`python main.py`

更适合有多级包结构的项目。后者可能让 Python 只把当前目录当作搜索起点，从而导致上层包无法找到。

### 3. 检查当前工作目录和文件目录是否混淆

“当前工作目录”是启动命令时所在的位置，不一定等于当前正在执行的 `.py` 文件所在的位置。

例如你在编辑器中打开了 `project/main.py`，但编辑器的运行配置把工作目录设成了别的目录，程序就可能无法找到同级模块。命令行中也一样：你从哪个目录执行命令，会影响 Python 的模块搜索环境。

可以临时打印当前工作目录：

`import os`

`print(os.getcwd())`

也可以查看模块搜索路径：

`import sys`

`print(sys.path)`

如果目标文件所在目录不在搜索路径中，导入自然会失败。这里的重点是定位问题，不建议把 `sys.path.append()` 作为长期解决方案。

### 4. 检查是否存在同名文件或目录

当报错不是“找不到模块”，而是“模块中没有某个属性”，可能是加载了错误的同名文件。

例如：

`from json import loads`

如果项目目录中存在自定义的 `json.py`，Python 可能导入自定义文件。此时即使文件名看起来没问题，模块内容也可能完全不符合预期。

排查方法包括：

- 检查项目中是否有与标准库同名的文件；
- 检查是否有同名目录；
- 查看导入模块的实际位置；
- 删除运行过程中产生的缓存后重新启动。

可以用以下方式查看模块文件位置：

`import user`

`print(user.__file__)`

如果打印出来的路径不是你预期的那个文件，就说明发生了名称冲突或搜索路径优先级问题。

## 四、项目中更稳妥的导入方式：先设计目录，再写代码

引入 `.py` 文件的难点，通常不是 `import` 语句，而是项目目录没有形成清晰的边界。一个适合长期维护的项目，应该让入口文件、业务模块、公共模块和测试文件各自承担明确职责。

例如可以使用这样的结构：

`project/`

`├── run.py`

`├── app/`

`│   ├── __init__.py`

`│   ├── config.py`

`│   ├── services/`

`│   │   ├── __init__.py`

`│   │   └── user_service.py`

`│   └── controllers/`

`│       ├── __init__.py`

`│       └── user_controller.py`

`└── tests/`

`    └── test_user_service.py`

此时，入口文件负责启动程序，服务模块负责业务逻辑，配置模块负责配置读取，测试目录负责验证功能。模块之间按照职责引用，而不是通过层层修改路径来勉强连接。

如果 `user_controller.py` 需要使用服务层函数，可以写：

`from app.services.user_service import say_hello`

如果 `run.py` 需要启动控制器，可以写：

`from app.controllers.user_controller import handle_user`

这种结构的好处是，文件移动和项目扩展时，导入关系更容易理解。相反，如果所有文件都依靠手动拼接路径，项目一旦部署、测试或由其他入口启动，就容易出现“本地能运行，换环境失败”的问题。

### 1. 不要把业务代码放到随意修改的路径中

有些人遇到导入失败，会在文件中加入：

`import sys`

`sys.path.append("某个目录")`

这确实可能让程序暂时找到目标文件，但它会带来几个长期问题：相对路径依赖启动位置，路径优先级不透明，部署时容易失效，其他开发者也难以判断模块从哪里加载。

更合理的解决顺序是：

- 将相关文件放入清晰的包目录；
- 从项目根目录启动程序；
- 使用完整包路径导入；
- 必要时配置正规的项目安装方式。

只有在临时脚本、一次性数据处理任务或明确受控的运行环境中，才考虑动态修改搜索路径，而且应当把这种做法限制在很小的范围内。

### 2. 包内导入和直接运行要统一

假设 `app/services/user_service.py` 中写了：

`from ..config import DATABASE_URL`

如果直接执行：

`python app/services/user_service.py`

可能出现“没有已知的父包”之类的错误。原因是这个文件被当作顶层脚本运行，而不是作为 `app.services.user_service` 包模块运行。

正确的思路不是把相对导入改成一串路径，而是在项目根目录执行：

`python -m app.services.user_service`

如果这个文件本身不是程序入口，而只是业务模块，更建议不要直接执行它，而是由 `run.py` 或测试文件调用。**模块怎么被运行，会直接影响它能否使用包内导入。**

## 五、常见导入误区，以及更合适的处理方式

### 1. 把 `.py` 后缀写进导入语句

错误思路是把文件当作普通路径处理。Python 的导入对象是模块，模块名不包含 `.py` 后缀。

文件是 `config.py`，写法应为：

`import config`

或者：

`from config import DATABASE_URL`

### 2. 以为只要文件在电脑上就能导入

Python 不会自动扫描整个电脑寻找文件。它只会在模块搜索路径中查找。文件存在于桌面、下载目录或其他项目目录，并不意味着当前程序可以直接导入。

如果文件确实属于当前项目，应把它移动到项目包内，或通过正规的包安装方式让解释器识别。不要把整个电脑的多个目录都加入搜索路径，否则同名模块冲突会越来越难排查。

### 3. 过度使用 `from 模块 import *`

这种方式省略了模块前缀，但会牺牲可读性。尤其是在大型文件中，看到 `parse_data()` 时，读者无法确定它来自哪个模块。

更建议写：

`import data_parser`

`data_parser.parse_data()`

或者只导入少量明确对象：

`from data_parser import parse_data`

代码中应优先保留来源信息，而不是只追求调用时少写几个字符。

### 4. 模块之间互相导入，形成循环依赖

例如 `a.py` 引入 `b.py`，而 `b.py` 又引入 `a.py`，就可能产生循环导入。常见表现是模块还没有初始化完成，就访问不到其中的函数或类。

解决循环依赖时，不要只把导入语句挪到函数内部来“压住”错误。那可能暂时有效，但没有消除结构问题。更稳妥的办法是重新划分职责：

- 把双方都需要的常量或公共函数放进独立的 `common.py`；
- 让底层模块不要反向依赖上层模块；
- 用参数传递对象，减少模块之间的隐藏依赖；
- 保持依赖方向从基础模块指向业务模块，而不是相互指向。

如果两个模块确实属于同一职责边界，也可以考虑合并，而不是继续拆分出更多相互引用的文件。

### 5. 忽略缓存文件造成的误判

Python 运行后可能在目录中生成 `__pycache__` 和字节码缓存。多数情况下缓存会自动管理，不需要手动处理。但当文件重命名、目录移动或导入对象发生变化时，旧缓存可能让排查过程变得混乱。

遇到导入结果与代码明显不一致时，可以停止程序，确认实际加载路径，清理相关缓存后重新运行。真正需要优先确认的仍然是模块路径和文件名称，不能把所有问题都归因于缓存。

## 六、从脚本到项目，怎样建立稳定的导入习惯

如果只是两个文件放在同一目录，直接使用 `import 文件名` 就够了。如果已经出现多级目录、测试、部署或多人协作，就应当从一开始建立包结构，而不是等导入错误越来越多后再修补。

可以按照下面的顺序推进：

1. 先确定一个项目根目录，把所有业务代码放在根目录下的包中。
2. 为业务目录设置清晰的模块职责，避免一个文件同时承担配置、数据库、接口和工具函数。
3. 从项目根目录运行入口，优先使用完整包路径或模块方式启动。
4. 导入时区分“模块导入”和“对象导入”，让代码能够清楚表达依赖来源。

判断一个导入方案是否合适，可以看三个问题：换到另一台电脑后是否仍能运行；从测试入口启动时是否仍能找到模块；移动当前文件后，是否只需要修改少量明确的包路径。如果三个问题都能回答清楚，说明目录和导入关系基本稳定。

对于临时脚本，简单并不等于随意。哪怕只有一个数据处理文件，也应避免依赖当前电脑的绝对路径。可以把输入文件、处理逻辑和输出逻辑分开，把路径作为参数传入，这样脚本从命令行、编辑器或定时任务启动时，行为会更一致。

若需要引入第三方库，原理仍然相同：Python 会在环境中的模块搜索位置查找它。区别在于，第三方库通常通过当前解释器对应的包管理环境安装，而本地 `.py` 文件则依赖项目目录和包结构。安装成功但导入失败时，应先确认“安装库的 Python”和“运行代码的 Python”是不是同一个解释器。

把 .py 文件当作一个模块来导入即可。如果文件名是 mymodule.py，可以在同目录下直接写 import mymodule，之后通过 mymodule.函数名 或 mymodule.类名 使用里面的内容。若只想导入其中某个对象，也可以写 from mymodule import 函数名。

使用 import 语句导入模块

我有一个单独的 Python 文件，想在另一个脚本里直接复用里面的函数、类或变量，应该怎么写导入语句？

在 Python 中，怎样把一个 .py 文件里的代码用到当前脚本里？

可以把目标文件所在目录加入到 Python 搜索路径中，例如通过 sys.path.append() 临时添加目录，也可以把项目整理成包结构，用相对导入或绝对导入来引用模块。若是长期维护的项目，推荐使用包结构，这样代码更清晰，也更容易管理。

调整路径或使用包结构导入

我的脚本和目标 .py 文件放在不同文件夹里，直接导入会报错，这种情况该怎么处理？

如果两个 Python 文件不在同一个目录，怎么才能互相引用？

这是因为 Python 在导入模块时，会执行模块顶层的代码。可以把不希望被导入时执行的部分放到 if __name__ == '__main__': 下面，这样文件被直接运行时会执行这些代码，被其他文件导入时就不会执行。

用主入口判断避免导入时自动执行

我只是想使用某个函数，但在导入这个文件时，文件里的测试代码或打印内容也被运行了，这是正常的吗？

导入 py 文件时，为什么有时会执行里面的代码？

PingCodeDocs

Python 引入 py 文件主要使用 import 和 from 模块 import 对象，文件名不带 py 后缀。同目录文件可直接导入，跨目录文件应通过清晰的包结构和点号路径导入，并从项目根目录启动。遇到导入失败时，应依次检查文件名、目录结构、运行入口、工作目录、搜索路径和同名模块，避免长期依赖 sys.path.append 或随意修改环境变量。

python怎么引入py文件