初次接触Python的人往往会疑惑：同样是写Python代码，为什么有的文件叫main.py，有的却是setup.py、__init__.py，运行之后目录里还冒出一堆.pyc文件？理解Python文件的后缀约定，是读懂一个项目结构的第一步。本文将从最常见的.py讲起，逐一拆解Python生态中各种文件后缀的用途。
.py：Python源码文件的标准后缀
Python源代码文件的标准后缀是.py，任何包含Python代码的纯文本文件都应该使用这个后缀。当解释器执行一个.py文件时，会先读取源码，编译成字节码，再交给Python虚拟机运行。这是整个Python体系中出现频率最高、也是最重要的一种文件。
除了普通脚本，社区还形成了一些约定命名的.py文件，它们本身后缀不变，但文件名有特殊含义：
- __init__.py：放在目录中，标记该目录是一个包。在较老的Python版本中，没有这个文件的目录无法被import；从Python 3.3开始虽然命名空间包可以省略它，但显式保留它仍然是主流做法，也可以在其中编写包的初始化逻辑。
- setup.py：传统打包配置文件，配合setuptools描述项目元数据、依赖和入口，用于
python setup.py install等命令。现在官方更推荐使用pyproject.toml替代。 - __main__.py：当一个目录或zip包被直接执行时，解释器会寻找这个文件作为入口，例如
python -m mypackage就是运行包内的__main__.py。 - conftest.py：pytest测试框架约定文件，用来存放共享的fixture和钩子函数，pytest会自动收集它而无需import。
- manage.py：Django项目的命令行入口文件，相信写过Django的人都不陌生。
一个简单的示例如下，文件必须保存为.py后缀才能被直接执行：
# hello.py
def greet(name):
return f"hello, {name}"
if __name__ == "__main__":
print(greet("python"))
在命令行执行python hello.py即可看到输出。注意文件名本身也应符合标识符规则，避免使用中文、空格或以数字开头，否则import时会出问题。
.pyc与缓存：字节码文件是怎么来的
运行.py文件或import模块后，你可能会在__pycache__目录下发现后缀为.pyc的文件。这是Python将源码编译后得到的字节码缓存，目的是加快后续模块的加载速度——下次import同一模块时，如果源码没变，解释器直接读取缓存，省去重新编译的开销。
Python 3的解释性细节值得注意：.pyc文件不是模块本身，而只是优化加载的手段。即使删除全部__pycache__目录，程序依然能正常运行，只是首次运行会稍慢。判断缓存是否失效的依据是源文件的修改时间和大小，因此修改源码后旧缓存会自动失效并重新生成。
此外还有.pyo这种后缀，它曾用于优化编译的字节码，但从Python 3.5开始已被移除，统一合并到.pyc中。实践中有一条重要经验：在.gitignore里加上__pycache__/规则，避免把缓存文件提交到版本库，这是很多新手容易踩的坑。
.pyw、.pyi以及其他值得了解的后缀
在Windows平台上，.pyw后缀的文件用pythonw.exe运行，执行时不会弹出黑色控制台窗口，非常适合开发纯图形界面程序，比如用tkinter或PyQt写的桌面工具。它的代码内容和.py完全一样，仅仅是关联的解释器不同。
.pyi是存根文件（stub file），由PEP 484引入，只包含类型注解而不包含实现逻辑，常见于mypy等静态类型检查工具。著名的typeshed项目就维护了大量标准库和第三方库的.pyi存根，让没有内联注解的库也能享受类型检查。
其他相关后缀还包括：扩展模块源文件.pyx（Cython专用，可编译成C扩展）、打包工具配置.pyproject.toml（严格说是toml后缀）、以及打包产物的wheel和egg文件。整理成表格更直观：
| 后缀 | 含义 | 典型用途 |
|---|---|---|
| .py | Python源码 | 编写脚本和模块 |
| .pyc | 字节码缓存 | 自动生成，加速import |
| .pyw | 无控制台的源码 | Windows GUI程序 |
| .pyi | 类型存根文件 | 静态类型检查 |
| .pyx | Cython源码 | 编写C扩展模块 |
日常开发中的实践建议
对绝大多数开发者来说，日常只需要记住一条：自己编写的Python代码文件统一使用.py后缀。其余后缀要么是工具自动生成的产物，要么用于特定场景，遇到时查表理解即可。
命名时建议遵循PEP 8规范：模块名使用全小写字母加下划线，例如user_service.py；避免与标准库模块重名，比如不要把自己的文件命名为random.py或os.py，否则import时会优先加载当前目录下的同名文件，导致诡异的行为。这类问题排查起来非常耗时，是新手常见的事故来源。
最后提醒一点，如果你的.py文件需要被其他模块import，目录结构中记得为每个包目录放置__init__.py（即使内容为空），并在项目根目录配置好.gitignore排除__pycache__。这些小习惯能让你项目的文件结构一目了然，也让协作者更快理解代码的组织方式。
python文件后缀.py文件python脚本修改时间：2026-09-14 23:34:47