What is the __pycache__ folder in Python?

What are these __pycache__ folders in my source? #

You may have noticed folders called __pycache__ popping up in your Python projects. These are present in the root of your project source, and are repeated in all the package folders as well.

When Python executes a module for the first time, it compiles your .py files into bytecode, which is a lower-level version of your source code that the Python interpreter can execute more quickly.

It speeds up your program…

Rather than recompiling the source code every time you run your program, Python saves these compiled bytecode files in the __pycache__ folder. These typically have a .pyc extension and also contain information about the Python version used to create them.

Filename format of .pyc files #

The naming convention for these files is usually in the format:

module_name.cpython-XY.pyc

For example, if you have a module named example.py and you are using Python 3.11, the compiled bytecode file would be named:

example.cpython-311.pyc

Bytecode? But Python is an interpreted language! #

Although Python is often described as an interpreted language, CPython, which is the standard Python interpreter, does not execute your .py file directly. Instead, it compiles the source code into an intermediate bytecode the first time a module is imported or when a script is run.

This bytecode is run (interpreted) by the Python Virtual Machine (PVM), which is part of the Python runtime environment.

Like Java, but not quite the same

Java developers may be familiar with a similar concept, where Java source code is compiled into bytecode (.class files) that runs on the Java Virtual Machine (JVM). However, the compiled .pyc files are not meant for distribution and are specific to the Python version and environment (OS, architecture) they were created in.

Can I delete the __pycache__ folders? #

There is no problem deleting the __pycache__ folders. Python will simply regenerate them the next time you run your program.

Usually, you would want to clean up these folders if you are preparing your project for distribution.

You can use file utilities available on your operating system like find/rm on Linux/Mac systems or del on Windows to remove these folders if needed.

However, if you have Python version 3.9 or above, you can use the pyclean module, which is OS-agnostic.

To use it, first install the module via pip:

$ pip install pyclean

Then run the following command in your terminal:

$ python -m pyclean  .
Cleaning directory .
Total 4 files, 2 directories removed.

See the pyclean PyPI page for more details on installation and usage.

Should I include __pycache__ in my version control? #

You should typically not include the __pycache__ folders in your version control system (like Git). Since these files are dependent on the specific Python version, the files inside __pycache__ would increase as different developers may use different Python versions. Also, it causes merge conflicts and ’noisy’ diffs.

For Git, you can add the following lines to your .gitignore file to exclude these folders:

# Ignore Python byte‑code caches
__pycache__/
*.py[cod]   

Note that the *.py[cod] pattern includes .pyo and .pyd files as well. The .pyo files are compiled Python files produced by optimization flags, and .pyd files are Windows-specific compiled extension modules.

Customizing the __pycache__ location #

Starting from Python 3.8, you can customize the location of the __pycache__ directories using the PYTHONPYCACHEPREFIX environment variable. This allows you to specify a different directory for storing the bytecode cache files.

$ export PYTHONPYCACHEPREFIX=/path/to/your/cache

With this setting, Python will create the __pycache__ directories in the specified location instead of the default location.