What is __pycache__ in Python and can you delete it?

__pycache__ is a folder that Python creates automatically next to your code to store compiled bytecode (.pyc files) of the modules you import. It exists so Python can skip recompiling unchanged modules the next time they load. Deleting __pycache__ is safe: nothing breaks, Python rebuilds it on the next import, and the only cost is a slightly slower first start.

This guide explains what is inside the folder, how Python decides when to use or rebuild it, how to delete every __pycache__ folder in a project on Windows, macOS and Linux, and how to stop Python from creating it.

What is the __pycache__ folder in Python?

The __pycache__ folder is Python's bytecode cache. Before Python runs a module, it compiles the .py source into bytecode, a lower-level format the interpreter executes. When you import a module, Python saves that bytecode in a __pycache__ folder in the same directory as the source file, so the next import can load the ready-made bytecode instead of compiling again.

The folder appeared with Python 3.2 through PEP 3147. Before that, Python 2 wrote .pyc files directly beside each .py file, which cluttered folders and caused problems when several Python versions shared the same source: each version overwrote the other's cache. Moving the cache into its own folder, with a version tag in each file name, fixed both issues.

You see __pycache__ in almost any Python project, in virtual environments and inside installed packages under site-packages. It also shows up when you run Python through other tools, from IDEs to Python scripts used alongside Excel. The folder is a cache, not part of your program, which is why it is safe to remove.

What are the .pyc files inside __pycache__?

The .pyc files in __pycache__ are compiled bytecode versions of your modules, one per module and Python version. The Python tutorial describes the naming scheme as module.version.pyc, where the version part identifies the interpreter. A file named utils.py imported by CPython 3.13 is cached as __pycache__/utils.cpython-313.pyc.

Common file names you will find:

• module.cpython-312.pyc: regular bytecode for CPython 3.12.
• module.cpython-313.pyc: the same module cached by a second interpreter, which is why one folder can hold several copies.
• module.cpython-313.opt-1.pyc: created when Python runs with -O, which strips assert statements.
• module.cpython-313.opt-2.pyc: created with -OO, which also strips docstrings.

Two details surprise many developers. First, the script you run directly (python main.py) is never cached; only imported modules get a .pyc file. Second, bytecode does not make your program run faster. The Python documentation states that the only speed gain is how quickly modules load, so the benefit is shorter startup and import time, not faster execution.

How does Python know when to rebuild __pycache__?

Python checks each cached .pyc file against its source before using it, so a stale cache is rebuilt automatically. By default, each .pyc stores the last-modified timestamp and size of the .py file it came from. On import, Python compares those values with the current source; if they differ, it recompiles and overwrites the cache file.

Since Python 3.7 there is a second mode, hash-based .pyc files, which store a hash of the source contents instead of a timestamp. These are mainly used for reproducible builds and packaging, where timestamps are unreliable. Checked hash-based files are verified against the source on import; unchecked ones are trusted as long as they exist.

Python also ignores a .pyc in __pycache__ if the matching .py file is gone. That means deleting a source file and leaving its cache behind will not keep the old module importable from __pycache__. For everyday work, you never have to touch the folder to keep it in sync with your edits.

Can you delete __pycache__?

Yes, you can delete __pycache__ at any time without harming your code. The folder contains only derived data, and Python recreates it the next time it imports a module from that directory. The trade-off is a small, one-time delay while modules compile again, which is rarely noticeable outside very large projects.

Situations where clearing the cache makes sense:

• Cleaning a project before zipping it, sharing it or copying it to another machine.
• Removing leftovers after you renamed or deleted modules, so old cache files do not confuse you or your tools.
• Troubleshooting odd import behavior, for example after copying files with preserved timestamps or restoring a backup.
• Switching Python versions, when old cpython-3xx files from a removed interpreter take up space.

Situations where it adds nothing: inside a virtual environment or site-packages you use every day, deleting __pycache__ only makes the next imports slower while Python rebuilds it. If the directory is not writable for your user, Python still runs the code; it simply cannot save the cache and compiles in memory each time.

How to delete all __pycache__ folders in a project

To remove every __pycache__ folder at once, run a recursive delete from the project's root folder. Check that you are in the right directory first, because these commands remove folders permanently and do not use the Recycle Bin or Trash.

To clear the cache of a single folder, delete that one __pycache__ directory in File Explorer, Finder or your editor's file tree. Many developers add one of the commands above to a Makefile, a task runner or a clean script so the project can be reset with one command.

How to stop Python from creating __pycache__

You can tell Python not to write .pyc files, or to write them somewhere outside your project. Both options are documented in the Python command line reference:

• -B flag: python -B main.py runs without writing .pyc files for that run.
• PYTHONDONTWRITEBYTECODE: set this environment variable to any non-empty value (for example 1) to get the same effect for every run, which is common in Docker images.
• sys.dont_write_bytecode = True: set this at the top of a script to disable cache writing from code.
• PYTHONPYCACHEPREFIX or -X pycache_prefix=PATH: available since Python 3.8, these keep the cache but move it to a separate directory tree, so your source folders stay clean.

Disabling the cache is fine for small scripts and containers that run once. For larger applications, moving the cache with PYTHONPYCACHEPREFIX is usually the better choice, because you keep fast imports without the extra folders.

Should __pycache__ be in .gitignore?

Yes, __pycache__ should be excluded from version control. The files are generated, specific to each Python version and rebuilt on every machine, so committing them only adds noise to diffs and merge conflicts. GitHub's official Python.gitignore template starts its byte-compiled files section with these entries:

• __pycache__/
• *.py[codz]

If cache files were already committed, adding the rule is not enough: remove them from the index with git rm -r --cached on the affected folders, then commit. If you hit trouble pushing the cleanup, see our guide on fixing GitHub when it is not working. The same logic applies to deployment: leave __pycache__ out of archives and container images and let the target system build its own.

FAQ

Related: How to use the PY function for Python in Excel, Cascadia Code, Microsoft's open source coding font, Meld file and folder comparison tool