怎么禁止Python自动生成.pyc缓存文件

在运行或导入模块时，Python 默认会在同级目录下创建 __pycache__ 目录并生成 .pyc 字节码缓存文件。要彻底禁止这一行为，最直接有效的路径有三种：在启动命令中附加 -B 参数、在系统或容器中注入环境变量 PYTHONDONTWRITEBYTECODE=1，或者在代码执行导入前设置 sys.dont_write_bytecode = True。

一、为什么 Python 会自动生成 .pyc 文件

Python 是一门解释型与编译型结合的语言。当 Python 脚本导入（import）其它模块时，解释器为了加快下一次加载模块的速度，会首先将源代码（.py）编译为中间字节码，并默认写入硬盘上的 __pycache__ 目录中，后缀为 .cpython-<版本>.pyc。

如果在之后的运行中，源代码没有发生改动（通过校验源码文件的最后修改时间和哈希值判定），Python 就会跳过解析与编译步骤，直接载入 .pyc 文件执行。这一机制在大型项目或冷启动频繁的环境下能够节省模块导入时间。

为什么要禁止生成 .pyc 缓存？

虽然缓存能提升导入速度，但在许多现代开发与生产场景中，频繁生成的缓存文件会带来额外干扰：

• 容器镜像体积控制：在构建 Docker 镜像或打包轻量化环境时，无须保留仅供单次构建的临时字节码，避免膨胀镜像层体积。
• 只读文件系统报错：在 AWS Lambda、只读挂载的 Kubernetes 容器或光盘等写保护介质中运行 Python，解释器尝试写入 __pycache__ 会触发权限警告或异常。
• 多版本与权限冲突：开发环境中多个用户或容器以不同权限挂载同一份代码卷时，__pycache__ 的权限差异常导致其它使用者无法读写或发生混乱。
• 代码目录保持纯净：在自动化测试、代码审计或临时排查脚本时，分散在各级子目录中的 __pycache__ 容易混入归档包中。

二、方法一：命令行参数 -B（单次执行最简方式）

如果在某次单独执行脚本或调试时不想生成缓存，可以在调用 python 命令时加入大写的 -B 选项。

1. 基本使用示例

在终端中以 -B 选项运行目标脚本：

# 运行单个脚本文件
python -B main.py

# 以模块方式运行（如 unittest、pytest）
python -B -m unittest discover

2. 在脚本首行（Shebang）中固化 -B

在 Linux 或 macOS 环境下，如果是作为可执行脚本直接通过 ./main.py 运行，可以在文件第一行的 Shebang 中通过 env -S 传递参数：

#!/usr/bin/env -S python3 -B
# -*- coding: utf-8 -*-

import utils
print("脚本执行完成，且不会生成 utils 的 .pyc 缓存。")

赋予执行权限后直接调用：

chmod +x main.py
./main.py

三、方法二：环境变量 PYTHONDONTWRITEBYTECODE（全环境生效）

如果希望在当前终端会话、系统服务或 Docker 容器内全局生效，而不需要为每一次 python 调用手动附加 -B，设置环境变量 PYTHONDONTWRITEBYTECODE 是最标准、最推荐的方案。

只要该环境变量被赋值为非空字符串（通常设置为 1），Python 解释器在启动时就会自动关闭字节码写入。

1. Linux 与 macOS 的具体操作

当前终端临时生效：

export PYTHONDONTWRITEBYTECODE=1

执行该命令后，在当前终端窗口后续执行的所有 Python 命令都将禁止生成 .pyc。

当前用户永久生效：

根据当前使用的 Shell（通过 echo $SHELL 确认），将该环境变量加入配置文件中：

# 若使用 bash
echo 'export PYTHONDONTWRITEBYTECODE=1' >> ~/.bashrc
source ~/.bashrc

# 若使用 zsh（macOS 默认）
echo 'export PYTHONDONTWRITEBYTECODE=1' >> ~/.zshrc
source ~/.zshrc

2. Windows 系统的具体操作

PowerShell 环境：

# 当前会话临时生效
$env:PYTHONDONTWRITEBYTECODE = 1

# 用户级永久生效
[System.Environment]::SetEnvironmentVariable('PYTHONDONTWRITEBYTECODE', '1', [System.EnvironmentVariableTarget]::User)

CMD（命令提示符）环境：

rem 当前会话临时生效
set PYTHONDONTWRITEBYTECODE=1

rem 永久写入系统用户变量
setx PYTHONDONTWRITEBYTECODE 1

3. Dockerfile 容器化最佳实践

在容器构建与镜像优化中，通常会同时关闭字节码缓存与输出缓冲（让日志即时输出到控制台）。在 Dockerfile 头部声明即可：

FROM python:3.11-slim

# 关键：1. 禁止写.pyc缓存 2. 实时刷新日志输出
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["python", "app.py"]

四、方法三：代码层配置 sys.dont_write_bytecode（运行时控制）

如果不想依赖外部环境的配置，或者你正在编写一个框架、CLI 工具，希望无论用户以何种方式运行该项目，都内部强制不落盘缓存，可以直接在 Python 源码中控制。

Python 的标准库 sys 模块提供了内置布尔属性 sys.dont_write_bytecode。将其赋值为 True 即可通知解释器停止写入缓存。

代码示例与生效时机

# main.py
import sys

# 关键设置：必须放在导入其他自定义模块之前！
sys.dont_write_bytecode = True

# 紧接着导入业务模块
import database_service
import utils

def main():
    print("业务逻辑开始运行...")
    database_service.init_db()

if __name__ == "__main__":
    main()

五、清理已有缓存与禁止结果验证

无论采用上述哪一种禁止方式，已经存在的 .pyc 文件和 __pycache__ 目录都不会被自动删除。 为了验证禁止配置是否真正生效，正确的操作步骤是：先将当前项目目录下的所有存量 __pycache__ 清理干净，然后再执行脚本进行观察。

1. 清理已有缓存命令

Linux / macOS：

# 递归删除当前目录下所有的 __pycache__ 文件夹及其内容
find . -type d -name "__pycache__" -exec rm -rf {} +

# 或者直接递归删除所有的 .pyc 文件
find . -name "*.pyc" -delete

Windows PowerShell：

# 递归搜索并删除所有的 __pycache__ 目录
Get-ChildItem -Path . -Filter "__pycache__" -Recurse -Force | Remove-Item -Recurse -Force

# 递归搜索并删除所有的 .pyc 文件
Get-ChildItem -Path . -Filter "*.pyc" -Recurse -Force | Remove-Item -Force

2. 执行验证流程

清理完毕后，使用 -B 或在环境变量生效状态下运行程序：

python -B main.py

运行完成后，在终端中再次运行查找命令：

find . -name "*.pyc"

六、方案对比与选型建议

三种方案在作用范围、维护成本与适用环境上各有侧重。下表给出了客观横向对比，帮助读者在具体场景中做出选择：

七、常见问题与注意事项

1. 禁止生成 .pyc 会降低代码的运行速度吗？

不会降低业务计算性能。
.pyc 文件存储的仅仅是编译好的字节码。禁止写入后，Python 依然会在每次启动时将源码在内存中编译为字节码并执行。一旦代码进入内存运行阶段，CPU 执行字节码的速率与从 .pyc 文件加载完全一致。唯一的微小开销是进程刚启动时导入模块的解析耗时（对于通常的项目仅有数毫秒到几十毫秒的差异）。

2. 为什么直接执行的主入口文件本身没有看到 .pyc？

在 Python 的默认设计中，通过 python entry.py 直接作为主程序入口运行的文件，本身就不会被生成 .pyc 缓存。Python 只为通过 import 语句导入的第三方或自建模块生成 .pyc 文件。如果你的项目只有一个单独的代码文件且未导入其他自建模块，即便不加任何禁止参数，也不会在同级目录下产生 __pycache__。

3. 是否还需要配置 .gitignore？

强烈建议始终保留。
即使你在开发环境中配置了环境变量或参数，团队中其他成员或某些外部工具仍可能无意中触发缓存生成。在项目的 .gitignore 文件中加入以下规则，是代码版本控制的标准防护兜底：

# 字节码与缓存规则兜底
__pycache__/
*.py[cod]
*$py.class