__pycache__ in Python: What It Is and When to Delete It

Name

Kana Mikami

Published on 6/20/2023

Updated on 7/13/2026

__pycache__ is a folder Python creates automatically when a module is imported. It stores compiled bytecode files (.pyc) so that the next run can skip recompiling your source code. It is safe to delete, safe to ignore in Git, and it will always come back — that is by design.

Quick facts before the details:

What is __pycache__ in Python?

Python is an interpreted language, but it doesn't re-interpret every .py file from scratch each time. When a module is imported, Python compiles the source to bytecode — a lightweight, low-level representation — and stores it as a .pyc file inside __pycache__.

On the next run, Python looks for an up-to-date .pyc file:

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

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

Each .pyc file name carries an interpreter tag (e.g. cpython-311 for CPython 3.11) so bytecode from multiple Python versions can co-exist without conflicts. You will see this matter when using:

• Virtual environments
• System Python alongside project-specific Python
• Tools like pyenv, conda, or Docker images

Where is the __pycache__ folder located?

__pycache__ appears in the same directory as the module that was imported:

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

If you import modules from other directories, each of those directories gets its own __pycache__. Virtual environments contain many of them inside installed packages — that is normal and expected.

Note: __pycache__ is created when a file is imported, not when it is run directly as a script. That's why running python main.py creates bytecode for utils.py (imported) but not for main.py itself.

Is it safe to delete __pycache__?

Yes. Deleting __pycache__ never breaks anything. Python detects the missing .pyc, recompiles the .py source, and recreates the folder on the next run. The only cost is that the first run after deletion is slightly slower.

Remove all __pycache__ folders recursively:

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

On Windows (PowerShell):

Get-ChildItem -Recurse -Directory -Filter __pycache__ | Remove-Item -Recurse -Force

Typical reasons to delete it:

• Debugging import issues or stale-bytecode weirdness (e.g. after renaming or moving modules)
• Cleaning a project before packaging or a Docker build
• Reducing noise before an archive/export

If you are chasing an import error that "shouldn't happen", clearing __pycache__ is a cheap first step — stale bytecode occasionally masks renames. See our guide on fixing circular imports in Python for the related class of import problems.

Why does __pycache__ keep coming back?

Because caching bytecode is Python's default behavior — every import triggers it. Deleting the folder does not turn the mechanism off. If you don't want it created at all, disable bytecode writing (next section) instead of deleting the folder repeatedly.

How to disable __pycache__ (PYTHONDONTWRITEBYTECODE)

Set the environment variable:

export PYTHONDONTWRITEBYTECODE=1

Or pass the -B flag for a single run:

python -B main.py

When enabled, Python won't write .pyc files and won't create __pycache__ folders. Common in:

• Docker images (smaller layers)
• CI pipelines
• Short-lived scripts where import speed is irrelevant

To make it permanent, add the export line to your shell configuration (e.g. ~/.bashrc or ~/.zshrc). Trade-off: every run pays the full compile cost, so leave caching on for large codebases you run repeatedly.

How to ignore __pycache__ in Git

.pyc files are machine-generated and interpreter-specific, so they don't belong in version control. Add to .gitignore:

__pycache__/
*.pyc

The *.pyc rule also catches bytecode from legacy Python 2, which placed .pyc files next to the .py source instead of in __pycache__.

If __pycache__ was already committed before you added the rule, untrack it once:

git rm -r --cached __pycache__

How does __pycache__ speed up Python?

A normal (cold) run of a Python file involves:

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

With an up-to-date .pyc, steps 1–3 are skipped. The effect is on startup and import time — your code does not execute any faster afterward. The difference is most noticeable in large codebases with many modules.

Hash-based .pyc files (PEP 552)

Python supports two invalidation modes:

• Timestamp-based .pyc (default) — invalidated when the source's mtime changes
• Hash-based .pyc — invalidated when the source's content hash changes, designed for reproducible builds, packaging, and Docker images

FAQ

What is the purpose of the __pycache__ folder?

It stores compiled .pyc bytecode files so Python can skip recompiling unchanged modules, making imports and startup faster on subsequent runs.

Is it safe to delete __pycache__?

Yes. Python regenerates it automatically the next time your code runs. Only the first run after deletion is slightly slower.

Should I commit __pycache__ to Git?

No. Add __pycache__/ and *.pyc to your .gitignore. Bytecode is machine- and version-specific and is regenerated on demand.

How do I stop Python from creating __pycache__?

Set the environment variable PYTHONDONTWRITEBYTECODE=1, or run Python with the -B flag. Python will then skip writing .pyc files entirely.

Why is there a __pycache__ folder inside my virtual environment?

Installed packages generate .pyc files the first time they are imported. Many __pycache__ folders inside venv/site-packages are normal and safe to leave alone.

Related guides

• How to fix circular imports in Python
• How to check your Python version
• How to upgrade Python

Working in Jupyter notebooks? PyGWalker (GitHub (opens in a new tab)) is an open-source Python library that turns your pandas or polars dataframe into a Tableau-like visual exploration interface — one import, no plotting code.