Skip to content

理解 Python 中的 pycache：你需要知道的一切

Kana Mikami
Name
Kana Mikami

Updated on

当你运行 Python 脚本时，可能会在项目里看到一个名为 __pycache__ 的文件夹。它看起来似乎无关紧要，但实际上在 Python 高效执行程序的过程中扮演着关键角色。本文会说明 __pycache__ 文件夹是什么、为什么 Python 会生成它，以及你如何安全地管理或删除它。

Python 是一门解释型语言，但它不会在每次运行时都从头解释每一个 .py 文件。Python 会先把源码编译成 bytecode（字节码）——一种更轻量、更底层、可更快执行的表示形式。这些编译好的字节码文件（扩展名为 .pyc）就存储在 __pycache__ 文件夹中。

想要在不用写代码的情况下，快速从 Python Pandas DataFrame 创建数据可视化？

PyGWalker 是一个用于数据可视化式探索分析的 Python 库。
PyGWalker (opens in a new tab) 可以直接在 Jupyter Notebook 中，将你的 pandas 或 polars dataframe 变成类似 Tableau 的交互界面。

PyGWalker for Data visualization (opens in a new tab)

Python 中的 pycache 是什么？

当 Python 运行一个 module 时，会自动创建 __pycache__ 文件夹。Python 会在其中存放 .pyc 文件——也就是 .py 文件编译之后的字节码版本。

字节码是为更快执行而设计的。当你运行脚本时，Python 会查找是否存在最新的 .pyc 文件：

  • 如果存在并且与当前源码匹配 → Python 会直接加载 .pyc 文件。
  • 如果不存在或已过期 → Python 会重新编译源码，生成新的 .pyc 文件，并存入 __pycache__。

为什么文件名像 module.cpython-310.pyc

较新的 Python 会在文件名中加入解释器标记（例如 cpython-311），这样多个 Python 版本可以并存而不互相冲突。

这在以下场景中特别重要：

  • 使用 virtual environment 时
  • 同时存在系统 Python 和环境特定的 Python 时
  • 使用 pyenv、conda 或 Docker image 等工具时

pycache 文件夹在哪？

__pycache__ 文件夹会出现在与被运行的 Python module 相同的目录下。

示例结构：

my_project/
    main.py
    utils.py
    __pycache__/
        main.cpython-311.pyc
        utils.cpython-311.pyc

如果你从另一个目录 import 一个 module，那么那个目录里也会生成自己的 __pycache__。

在 virtual environment 中

virtual environment 中的已安装包内部通常会包含很多 __pycache__ 文件夹。这是正常现象——当 package 被 import 时，就会第一次生成 .pyc 文件。

pycache 如何让 Python 脚本更快？

正常运行一个 Python 脚本需要：

  1. 解析源代码文本
  2. 构建 Abstract Syntax Tree（AST，抽象语法树）
  3. 将 AST 编译为 bytecode
  4. 执行 bytecode

当 Python 找到最新的 .pyc 文件时，会跳过步骤 1–3。因此：

  • 第一次运行可能稍微慢一点
  • 后续运行会更快（尤其是在大型代码库中）

基于哈希的 pyc 文件（PEP 552）

较新的 Python 支持两种 .pyc 机制：

  • 默认的基于时间戳的 .pyc
  • 基于哈希的 .pyc（用于可复现构建、打包、Docker image 等）

这让字节码生成在自动化或容器化环境中更加稳定、可预测。

我可以删除 pycache 文件夹吗？

可以 —— 删除 __pycache__ 是安全的。

Python 会在你下次运行脚本时自动重新创建它。唯一的影响是：下一次运行时会因为重新编译稍微慢一点。

递归删除所有 __pycache__ 文件夹：

find . -type d -name __pycache__ -exec rm -r {} \+

常见的删除 pycache 场景

  • 调试 import 相关问题
  • 在重命名 / 移动 module 之后
  • 打包部署前
  • 在 Git 提交或构建 Docker 前减少无关文件

如何禁用 pycache 文件的生成？

可以通过设置环境变量来禁用 .pyc 生成：

export PYTHONDONTWRITEBYTECODE=1

当这个变量生效时：

  • Python 不会生成任何 .pyc 文件
  • 不会创建 __pycache__ 文件夹

常用于：

  • Docker image（减小层大小）
  • CI pipeline
  • 对性能要求不高的小脚本

如果想永久生效，可以把这个变量写入 shell 配置文件（如 ~/.bashrc）。

如何在 Git 中忽略 pycache 文件？

因为 .pyc 文件是机器相关、自动生成的，所以不应该纳入版本控制。

在 .gitignore 中加入：

__pycache__/
*.pyc

*.pyc 这条规则是可选的，但对于旧版 Python 可能会把 .pyc 放在 .py 旁边的情况很有帮助。

如果删除 pycache 文件夹会怎样？

程序不会出问题，你的脚本照样能运行。

Python 会：

  1. 发现 .pyc 缺失
  2. 重新编译 .py 文件
  3. 重新创建 __pycache__ 目录及 .pyc 文件

只有删除之后的第一次运行会稍微慢一点。

常见问题（FAQ）

1. Python 中 __pycache__ 文件夹的作用是什么？

该文件夹存放编译后的 .pyc 字节码文件，用来加快 Python 在后续运行时的启动速度。

2. 我可以删除 __pycache__ 文件夹吗？

可以。删除它是安全的。Python 会在你下次运行脚本时自动重新生成。

3. 如何在 Git 中忽略 __pycache__ 文件？

在 .gitignore 中加入：

__pycache__/
*.pyc