鸭梨公共文档

主题

Python 文件扩展名 ​

1. 文件扩展名列表 ​

扩展名含义
.pyPython 源代码文件
.pycPython 源代码编译后的字节码文件，.pyc 文件是 .py 文件经过编译后的文件，可直接被 Python 解释器执行
.pyo与 .pyc 文件类似，.pyo 文件是 .py 文件经过优化编译后的文件，.pyo 文件可以直接被 Python 解释器执行
.pydWindows 平台下的 Python 扩展模块，即动态链接库
.pywWindows 平台下的 Python 脚本文件，即无控制台的 Python 脚本文件，会使用 pythonw.exe 解释器执行
.pyzPython 3.5 以上版本支持的压缩包格式，类似于 Java 的 .jar 包，可以直接使用 python.exe 解释器执行
.pyzwWindows 平台下的 Python 压缩包文件，即无控制台的 Python 压缩包文件，会使用 pythonw.exe 解释器执行
.pyiPython 3.5 以上版本支持的存根文件，用于类型检查
.cyxCython 编写的 Python 扩展模块源代码文件
.pxiCython 声明文件[1]
.pxdCython 导入代码文件，即扩展模块头文件，类似于 C/C++ 的 .h 头文件
.pyx由 Cython 编写的 Python 扩展模块源代码文件，.pyx 文件必须先被编译成 .c 文件，再编译成库文件

2. 扩展名详解 ​

2.1 .py - Python 源代码文件 ​

最常见的 Python 文件格式，包含可读的 Python 源代码。

示例：

python
# hello.py
def greet(name):
    print(f"Hello, {name}!")

if __name__ == "__main__":
    greet("World")

运行：

bash
python hello.py

2.2 .pyc - 字节码文件 ​

Python 会自动将 .py 文件编译为字节码文件 .pyc，存储在 __pycache__ 目录中。这可以加快程序启动速度。

位置：__pycache__/hello.cpython-39.pyc（Python 3.9 示例）

手动编译：

python
import py_compile
py_compile.compile('hello.py')

或者使用命令行：

bash
python -m py_compile hello.py

2.3 .pyo - 优化字节码文件 ​

在 Python 2 中，使用 -O 或 -OO 标志可以生成优化的 .pyo 文件。Python 3 中已废弃独立的 .pyo 文件，优化选项会在 .pyc 文件名中体现。

Python 3 编译优化：

bash
python -O -m py_compile hello.py  # 生成 hello.cpython-39.opt-1.pyc
python -OO -m py_compile hello.py # 生成 hello.cpython-39.opt-2.pyc

2.4 .pyd - Windows 动态链接库 ​

在 Windows 上，.pyd 文件是编译好的 Python 扩展模块（类似于 Linux 上的 .so 文件）。

使用 C 扩展：

python
# 假设有一个 mymodule.pyd 文件
import mymodule
result = mymodule.some_function()

2.5 .pyw - Windows 无控制台脚本 ​

在 Windows 上运行 .pyw 文件不会显示控制台窗口，适合 GUI 应用。

示例：

python
# gui_app.pyw
import tkinter as tk

root = tk.Tk()
root.title("Hello")
tk.Label(root, text="Hello, World!").pack()
root.mainloop()

运行：

bash
pythonw gui_app.pyw

或者直接双击 .pyw 文件。

2.6 .pyz 和 .pyzw - Python ZIP 应用 ​

Python 3.5+ 支持将整个应用打包为 ZIP 文件，可以直接执行。

创建 .pyz 文件：

bash
# 创建目录结构
mkdir myapp
echo "print('Hello from ZIP!')" > myapp/__main__.py

# 打包
python -m zipapp myapp -o myapp.pyz

# 运行
python myapp.pyz

使用 Python 代码创建：

python
import zipapp

zipapp.create_archive('myapp', 'myapp.pyz', '/usr/bin/env python3')

2.7 .pyi - 类型存根文件 ​

.pyi 文件用于提供类型提示，供类型检查工具（如 mypy）使用。

示例：

python
# math_utils.py
def add(a, b):
    return a + b

# math_utils.pyi (类型存根)
def add(a: int, b: int) -> int: ...

类型检查工具会优先使用 .pyi 文件中的类型信息。

2.8 Cython 文件 (.pyx, .pxd, .pxi) ​

Cython 是 Python 的超集，可以编译为 C 扩展以提高性能。

示例 .pyx 文件：

python
# example.pyx
def fibonacci(int n):
    cdef int i
    cdef double a = 0.0, b = 1.0
    for i in range(n):
        a, b = b, a + b
    return a

编译：

python
# setup.py
from setuptools import setup
from Cython.Build import cythonize

setup(
    ext_modules=cythonize("example.pyx")
)
bash
python setup.py build_ext --inplace

使用：

python
import example
print(example.fibonacci(10))

3. 文件选择指南 ​

场景推荐扩展名说明
普通 Python 脚本.py标准的 Python 源代码文件
Windows GUI 应用.pyw运行时不显示控制台窗口
单文件分发应用.pyz将整个应用打包为单个可执行 ZIP 文件
类型提示.pyi为库提供类型信息
性能关键代码.pyx使用 Cython 编译为 C 扩展
预编译模块（自动生成）.pycPython 自动生成，加快加载速度
C/C++ 扩展（Windows）.pyd编译好的扩展模块

4. 注意事项 ​

4.1 .pyc 文件的版本兼容性 ​

.pyc 文件是特定于 Python 版本的，不同版本的 Python 无法共享字节码文件：

python
# Python 3.9 生成的 .pyc 无法被 Python 3.8 使用
# 文件名会包含版本信息：hello.cpython-39.pyc

4.2 清理 .pyc 文件 ​

可以使用以下命令清理项目中的 .pyc 文件：

bash
# Unix/Linux/Mac
find . -type f -name "*.pyc" -delete
find . -type d -name "__pycache__" -delete

# Windows
del /s /q *.pyc
for /d /r . %d in (__pycache__) do @if exist "%d" rd /s /q "%d"

# 使用 Python
python -Bc "import pathlib; [p.unlink() for p in pathlib.Path('.').rglob('*.py[co]')]"

4.3 禁用 .pyc 文件生成 ​

在某些情况下可能需要禁用 .pyc 文件的生成：

bash
# 使用环境变量
export PYTHONDONTWRITEBYTECODE=1

# 或使用命令行参数
python -B script.py

5. 参考资料 ​

  1. Python 官方文档 - 模块
  2. PEP 441 - 提高 Python ZIP 应用支持
  3. PEP 484 - 类型提示
  4. Cython 文档

  1. Cython，https://cython.readthedocs.io/en/latest/src/userguide/faq.html#what-is-the-difference-between-a-pxd-and-pxi-file-when-should-either-be-used ↩︎