Skip to content

Understanding pycache in Python: Everything You Need to Know

Kana Mikami
Name
Kana Mikami

Updated on

If you've ever run a Python script, you might have noticed a folder named __pycache__ appearing inside your project. It may look unimportant, but it plays a critical role in how Python executes your programs efficiently. In this guide, we’ll break down what the __pycache__ folder is, why Python generates it, and how you can manage or remove it safely.

Python is an interpreted language, but it doesn’t re-interpret every .py file from scratch each time you run it. Instead, Python compiles your source code into bytecode—a lightweight, low-level representation that can be executed more quickly. These compiled bytecode files (with the .pyc extension) are stored inside the __pycache__ folder.

Want to quickly create Data Visualization from Python Pandas Dataframe with no code?

PyGWalker is a Python library for Exploratory Data Analysis with Visualization.
PyGWalker (opens in a new tab) turns your pandas or polars dataframe into a Tableau-like interface directly inside Jupyter Notebook.

PyGWalker for Data visualization (opens in a new tab)

What is pycache in Python?

The __pycache__ folder is automatically created when Python runs a module. Inside it, Python stores .pyc files—a compiled, bytecode version of your .py file.

Bytecode is designed for faster execution. When you run a script, Python looks for an up-to-date .pyc file:

  • If it exists and matches the current source code → Python loads the .pyc file immediately.
  • If not → Python recompiles the source code, generates a new .pyc file, and stores it in __pycache__.

Why the file names look like module.cpython-310.pyc

Modern Python includes interpreter tagging (e.g., cpython-311) so multiple Python versions can co-exist without conflicts.

This is especially important when using:

  • Virtual environments
  • System Python + environment-specific Python
  • Tools like pyenv, conda, or Docker images

Where is the pycache folder located?

The __pycache__ folder appears in the same directory as the Python module being run.

Example structure:


my_project/
main.py
utils.py
**pycache**/
main.cpython-311.pyc
utils.cpython-311.pyc

If you import a module from another directory, that directory will also generate its own __pycache__.

In virtual environments

Virtual environments often contain many __pycache__ folders inside installed packages. This is normal—package imports generate .pyc files on first use.

How does pycache speed up Python scripts?

Running a Python script normally requires:

  1. Parsing the text
  2. Building an Abstract Syntax Tree (AST)
  3. Compiling the AST to bytecode
  4. Executing the bytecode

Steps 1–3 are skipped when Python finds an up-to-date .pyc file. This is why:

  • First run may be slightly slower
  • Subsequent runs are faster (especially in large codebases)

Hash-based pyc files (PEP 552)

Modern Python supports both:

  • Timestamp-based .pyc (default)
  • Hash-based .pyc (for reproducible builds, packaging, Docker images)

This makes bytecode generation more stable in automated or containerized environments.

Can I delete the pycache folder?

Yes — deleting __pycache__ is safe.

Python will recreate it automatically the next time you run your scripts. The only downside: your next execution may be slightly slower due to recompilation.

To remove all __pycache__ folders recursively:

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

Common use cases for deleting pycache

  • Debugging import issues
  • After renaming/relocating modules
  • When packaging for deployment
  • To reduce noise before a Git commit or Docker build

How do I disable the creation of pycache files?

You can disable .pyc creation by setting the environment variable:

export PYTHONDONTWRITEBYTECODE=1

When enabled:

  • Python will not generate any .pyc files
  • __pycache__ folders will not be created

This is commonly used in:

  • Docker images (to reduce layer size)
  • CI pipelines
  • Small scripts where performance is irrelevant

To make this setting permanent, add the variable to your shell configuration (e.g., ~/.bashrc).

How to Ignore pycache Files in Git

Since .pyc files are machine-specific and auto-generated, they should not be stored in version control.

Add this to your .gitignore:

__pycache__/
*.pyc

The *.pyc rule is optional but helpful when legacy Python versions place .pyc next to .py.

What Happens If I Delete the pycache Folder?

Nothing breaks. Your script will run normally.

Python will simply:

  1. Detect the missing .pyc
  2. Recompile the .py file
  3. Recreate the __pycache__ directory and .pyc file

Only the first run after deletion is slightly slower.

FAQ

1. What is the purpose of the __pycache__ folder in Python?

The folder stores compiled .pyc bytecode files, which make Python start faster on subsequent runs.

2. Can I delete the __pycache__ folder?

Yes. Deleting it is safe. Python regenerates it automatically.

3. How can I ignore __pycache__ files in Git?

Add this to your .gitignore:

__pycache__/
*.pyc