Python .gitignore Template
Python projects generate a distinctive set of file types that should always be excluded from version control. Unlike JavaScript, where the primary concern is node_modules, Python projects must manage virtual environments, compiled bytecode, distribution packages, and several testing and coverage artifacts that accumulate during development.
Virtual environments are the Python equivalent of node_modules in terms of .gitignore priority. Depending on the tool used to create them, they live in directories named venv, .venv, env, .env, virtualenv, or pyenv. All of these should be in your .gitignore. Virtual environments contain installed packages and Python interpreter binaries specific to your operating system and cannot be shared across different OS environments. They are fully reproducible from requirements.txt or pyproject.toml with pip install -r requirements.txt.
Python's bytecode cache (__pycache__ directories and .pyc files) is generated automatically when Python imports a module. These compiled bytecode files speed up subsequent imports but are fully regenerated automatically and must not be committed. They also create noisy diffs because they change every time the corresponding .py file changes, making git history difficult to read. The pattern **/__pycache__/ recursively excludes pycache directories throughout nested packages.
Distribution and packaging artifacts from setuptools, pip, and build should be excluded: dist/, build/, *.egg-info/, .eggs/. These are generated by python setup.py build or python -m build and represent release artifacts that should not be in the development repository (they belong in releases and package registries like PyPI). Committing .egg-info directories is a common mistake that creates confusion about installed vs. development versions.
Testing artifacts need to be excluded: .pytest_cache/ (pytest's cache for faster test reruns), .tox/ (tox's virtual environments for multi-Python testing), .coverage (coverage.py's data file), htmlcov/ (generated coverage HTML reports), and .hypothesis/ (Hypothesis's test database). These are generated during testing and should not be tracked.
Environment files (.env) must be in the .gitignore. Python projects commonly use python-dotenv for loading environment variables from .env files. Any .env file with real secrets is a critical security exclusion. Always provide a .env.example or document environment variables in README instead.
Template Preview
{"environment":"python","includesVirtualEnv":true,"includesPycache":true,"includesDistribution":true,"includesTesting":true,"includesEnvFiles":true,"includesEditorFiles":true}Customize this template with your own details using the free generator:
▸Open in GeneratorFAQ
- Should I commit requirements.txt or pyproject.toml?
- Yes, always commit your dependency specification files. requirements.txt (for pip) and pyproject.toml with pyproject.lock or requirements.lock (for Poetry, Hatch, PDM) are how others reproduce your environment. The lockfile, if your tool generates one, should also be committed for applications (to ensure reproducible installs) but is often not committed for libraries to give consumers flexibility in dependency resolution.
- What is the difference between __pycache__ and .pyc files in .gitignore?
- In Python 3, bytecode files (.pyc) are stored inside __pycache__ directories rather than alongside .py files. Excluding __pycache__/ recursively (using **/__pycache__/) covers both. However, some tools and legacy code may still create .pyc files in the same directory as the .py source, so including *.pyc as a separate pattern provides additional coverage. Including both is the safe approach.
- Should I commit the .python-version file used by pyenv?
- Yes, committing .python-version is good practice because it documents the Python version the project requires and allows pyenv to automatically switch to the correct version when you cd into the project directory. This prevents subtle bugs from Python version mismatches. Unlike the virtual environment itself, .python-version is a tiny text file containing just the version number (e.g., 3.12.3).