How to Ignore Python Bytecode Files and `__pycache__` Directories in Git

Add __pycache__/, *.py[cod], and *$py.class patterns to your .gitignore file to prevent Git from tracking Python compiled artifacts.

When you run Python code, the interpreter automatically generates compiled bytecode to speed up subsequent executions. These artifacts appear as .pyc files and __pycache__ directories throughout your project structure. According to the official github/gitignore repository, you should never commit these generated files to version control. Instead, use the canonical ignore patterns maintained in the Python.gitignore template.

Why Python Creates Bytecode and Cache Directories

Python compiles your .py source files into platform-independent bytecode to improve startup performance. The interpreter stores these compiled files in two ways:

• __pycache__/ directories: Modern Python versions (3.2+) store compiled modules in subdirectories named __pycache__ alongside your source files.
• .pyc, .pyo, and .pyd files: Legacy bytecode files and Windows Python extensions that may appear in your working directory.

Because these files are regenerated automatically and are specific to the Python version and platform, they create unnecessary noise in your Git history if tracked.

The Official Python.gitignore Patterns

The github/gitignore repository provides the industry-standard template for Python projects. The specific patterns for bytecode and cache files appear at the beginning of the Python.gitignore file.

Ignoring __pycache__ Directories

The pattern on line 2 of Python.gitignore targets the cache directories:

__pycache__/

This trailing slash tells Git to ignore any directory named __pycache__ at any level of your repository, regardless of what files it contains.

Ignoring Compiled Bytecode Files

Line 3 uses a character class to match multiple bytecode extensions simultaneously:

*.py[cod]

This single pattern ignores:

• *.pyc — Compiled Python bytecode
• *.pyo — Optimized bytecode (legacy, removed in Python 3.5+)
• *.pyd — Python extension modules on Windows

Jython-Specific Patterns

For projects that may run on Jython (Python on the JVM), line 4 adds:

*$py.class

This handles Jython's specific naming convention for compiled Java classes derived from Python modules.

How to Implement These Rules in Your Project

You have two approaches for applying these patterns: manually adding the specific rules or adopting the entire official template.

Minimal Manual Configuration

Create or edit your .gitignore file in the repository root and add the essential bytecode patterns:

# Python bytecode and cache

__pycache__/
*.py[cod]
*$py.class

This configuration is sufficient for most Python projects and prevents Git from tracking generated bytecode artifacts.

Using the Full Official Template

For comprehensive coverage including virtual environments, IDE files, and distribution artifacts, download the complete Python.gitignore from the github/gitignore repository:

curl -L https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore -o .gitignore

This command retrieves the official template maintained by GitHub, which includes the bytecode patterns along with additional rules for venv/, dist/, and other Python-specific files.

Verifying Your Configuration

After updating your .gitignore, verify that Git correctly ignores the bytecode files:

# Check if __pycache__ is ignored

git check-ignore -v __pycache__

# Check if a specific .pyc file is ignored

git check-ignore -v module.pyc

If configured correctly, these commands will output the matching pattern and the .gitignore file path. If you previously committed bytecode files, remove them from tracking while preserving local copies:

git rm -r --cached __pycache__
git rm --cached *.pyc
git commit -m "Remove compiled Python bytecode from tracking"

Summary

• Use __pycache__/ to ignore Python 3.2+ cache directories that store compiled modules.
• Use *.py[cod] to match .pyc, .pyo, and .pyd bytecode files in a single pattern.
• Use *$py.class for Jython compatibility when running Python on the JVM.
• Reference the official Python.gitignore from github/gitignore as the authoritative source for these patterns.
• Clean existing bytecode from your repository history using git rm --cached if you previously tracked these files.

Frequently Asked Questions

What is the difference between .pyc and .pyo files?

.pyc files contain standard compiled Python bytecode, generated automatically when you import a module. .pyo files were "optimized" bytecode generated when running Python with the -O flag. As of Python 3.5, .pyo files no longer exist; optimization is stored in .pyc files with different magic numbers. The *.py[cod] pattern in Python.gitignore covers both historical and current naming conventions.

Should I commit pycache to Git?

No, you should never commit __pycache__ directories to Git. These directories contain platform-specific and Python-version-specific compiled bytecode that is automatically regenerated when you run your code. Committing them creates unnecessary repository bloat, potential conflicts between different Python versions, and noise in your pull requests. Always add __pycache__/ to your .gitignore file as specified in the official github/gitignore template.

How do I remove already tracked bytecode files from Git?

If you previously committed bytecode files or __pycache__ directories before adding ignore rules, remove them from Git's index while preserving the local files using these commands:

git rm -r --cached __pycache__
git rm --cached *.pyc
git commit -m "Remove compiled Python bytecode from version control"

After committing these changes and ensuring your .gitignore contains the proper patterns, Git will stop tracking these files while leaving your local development environment intact.

Does the Python.gitignore template cover virtual environments?

Yes, the official Python.gitignore template includes comprehensive rules for virtual environments. Beyond the bytecode patterns (__pycache__/, *.py[cod]), the template ignores common virtual environment directories including venv/, env/, ENV/, and .env/ at the root level. It also excludes pip log files, pyenv version files, and environment configuration files. Using the full template ensures you ignore not just bytecode but all common Python artifacts that shouldn't be committed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}