Python源文件的标准扩展名是什么

一、标准扩展名 .py 的定义与操作流程

在计算机操作系统中，文件扩展名是操作系统与开发环境识别文件类型的重要依据。对于 Python 编程语言而言，源码文件本质上是采用 UTF-8 编码（自 Python 3 开始默认）存储的纯文本文件。官方语法规范与 PEP 8（Python 增强提案 8，Python 代码样式指南）均明确规定，Python 源代码必须以小写扩展名 .py 结尾。

为了验证一个标准 .py 文件的完整生命周期，我们可以通过以下具体步骤完成创建、编写与终端调用：

步骤 1：新建源代码文件并正确命名

使用任意代码编辑器（例如 VS Code、PyCharm）或简单的文本编辑器，在项目工作目录中新建一个空白文件，并将其命名为 hello.py。在命名时，必须确保文件名以英文字母命名，且扩展名为小写 .py。

步骤 2：写入标准 Python 代码

在 hello.py 中输入以下完整的 Python 示例代码并保存：

# hello.py
def build_greeting(target_name: str) -> str:
    """生成问候语句"""
    return f"欢迎使用标准 Python 文件：hello {target_name}"

if __name__ == "__main__":
    message = build_greeting("World")
    print(message)

步骤 3：在终端中调用解释器执行

打开系统命令行终端（Windows Terminal / PowerShell，或 macOS / Linux 的 Terminal），切换至 hello.py 所在的绝对或相对路径目录，输入以下调用指令：

python hello.py

（注：在部分 Linux 或 macOS 环境中，如果系统同时存在 Python 2 与 Python 3，则执行指令应为 python3 hello.py。）

完成上述步骤后，控制台如期输出了预期文本。整个过程体现了标准 .py 源文件从编写到执行的标准闭环。

二、为什么必须是 .py：直跑脚本与模块导入的区别

许多初学者在探索命令行操作时会发现一个现象：在 Linux 或 macOS 终端中，即使把文件命名为无扩展名的 hello 或者自定义的 hello.txt，只要在终端输入 python hello 或 python hello.txt，程序居然同样可以正常打印出运行结果。

这种看似“扩展名无关紧要”的现象容易引发误解，以为扩展名只是个人习惯。实际上，这是因为当你在命令行中执行 python [文件路径] 时，Python 解释器是将后面的参数单纯视为文件流路径。解释器只要能打开并读取其中的字符流，且内容符合 Python 语法，就会按脚本解释执行。

然而，一旦脱离单一脚本的直接运行，进入实际项目的模块化导入（import 机制），缺少 .py 扩展名就会导致整个代码架构立即瘫痪。

1. 模块导入系统的检索铁律

在 Python 工程中，代码复用是通过 import 语句实现的。例如，当你在 main.py 中编写：

import my_tools

Python 解释器的导入查找器（PathFinder）会自动在当前目录以及 sys.path 包含的所有路径中搜索目标模块。导入系统只识别符合既定规则的文件命名，其核心匹配顺序包括：

1. my_tools.py（标准 Python 纯文本源文件）
2. my_tools.pyc（已预编译的字节码缓存）
3. my_tools/__init__.py（包含初始化脚本的包目录）
4. C/C++ 动态链接库扩展（Windows 下为 my_tools.pyd，Unix 下为 my_tools.so）

如果你的工具文件命名为 my_tools.txt、my_tools.script 或没有扩展名的 my_tools，Python 的导入系统在扫描目录时会直接无视该文件，并在运行时抛出不可挽回的异常：

ModuleNotFoundError: No module named 'my_tools'

2. 现代工程工具链与 IDE 深度依赖

除了 Python 运行时导入机制以外，所有现代开发工具均以 .py 作为识别与解析的前提：

• 语法高亮与智能补全：VS Code 的 Pylance、PyCharm、Sublime Text 只有在检测到 .py 扩展名时，才会启动对应的 Python 语言服务器（LSP）。
• 静态类型检查：Mypy、Pyright 等类型检查工具通过 .py 解析模块依赖图谱。
• 代码风格格式化与检查：Black、Flake8、Ruff 等格式化与 Lint 工具默认仅过滤和处理 .py 结尾的文件。

三、容易混淆的常见相关扩展名辨析

在日常开发与项目目录中，除了最常见的 .py 以外，读者经常还会遇到形如 .pyw、.pyc、.pyi、.pyd 甚至 .ipynb 的文件。这些扩展名各自扮演着特定角色，但都不能替代标准源码 .py：

1. .pyw：用于避免 Windows 黑框的无控制台脚本

在 Windows 操作系统中，双击运行 .py 文件时，系统默认会调用控制台程序 python.exe，从而伴随弹出一个黑色命令行窗口。若开发的是基于 Tkinter、PyQt 或 wxPython 的图形界面（GUI）软件，黑色终端窗口会影响用户体验。

将扩展名更改为 .pyw 后，Windows 关联程序会自动切换为 pythonw.exe。其源码与 .py 完全一致，区别仅在于操作系统在加载时不为其分配控制台窗口。

2. .pyc：解释器自动生成的字节码缓存

首次导入一个 .py 模块时，Python 解释器会将其编译为虚拟机能够高效解析的字节码（Bytecode），并将结果保存在同级目录的 __pycache__ 文件夹中，后缀名以 .cpython-311.pyc 呈现。开发者严禁手动修改 .pyc 文件，它属于纯粹的运行期缓存，源码修改后解释器会自动根据文件修改时间戳重新编译。

3. .ipynb：Jupyter 交互式笔记本并非纯 Python 源码

数据分析与机器学习领域常用的 .ipynb 文件，其底层并不是 Python 纯文本代码，而是包含元数据、Markdown 描述、单元格代码及富媒体运行结果的 JSON 格式结构体。因此，.ipynb 无法直接被终端 python 命令当作源码执行，也无法直接被其他 .py 模块通过常规 import 引用，需通过专用工具（如 nbconvert）导出为 .py 文件后方可作为标准源文件使用。

四、源文件命名规范与生产环境避坑指南

知道了标准扩展名是 .py 还不够，在给 Python 文件命名前半部分时，如果不遵守命名约束，往往会引发极其隐蔽的系统级故障。

1. 命名合法性必须满足 Python 标识符规范

因为模块文件名在导入时会直接映射为 Python 代码中的变量名（标识符），所以文件名必须满足：

• 使用纯小写英文字母与下划线：根据 PEP 8 规定，模块名应保持全小写，各单词之间使用下划线（_）分隔，例如 payment_gateway.py。
• 严禁使用连字符/减号（Hyphen）：例如将文件命名为 my-script.py。在命令行直接运行 python my-script.py 可以成功，但是当其他文件试图写入 import my-script 时，Python 解释器会将 - 识别为算术减法运算符，导致直接报出 SyntaxError: invalid syntax 语法错误。
• 严禁以数字开头：例如 1st_crawler.py。由于数字不能作为变量首字符，import 1st_crawler 同样会被报出非法语法。

2. 跨平台大小写敏感性问题

Windows 与 macOS（默认 APFS 格式）的文件系统在查找文件时不区分大小写，例如在 Windows 上 import Tools 可以成功匹配并加载磁盘上的 tools.py。

然而绝大多数生产服务器运行的 Linux 环境是严格区分大小写的。如果本地代码写的是 import Tools，而磁盘文件为 tools.py，在本地开发与测试时一切正常，一旦部署到 Linux 服务器就会立刻报出 ModuleNotFoundError 导致服务宕机。因此，所有源文件及代码中的导入语句必须严格遵循一致的小写命名规范。

五、实战常见问题解答（FAQ）