Python Gitignore: Copy-Ready File With Every Line Explained

November 11, 2026 · 9 min read

Python Gitignore: The .gitignore Every Python Project Needs

A Python gitignore file tells Git which generated files to skip. That means __pycache__/ bytecode, virtual environments, build output, test caches and .env secrets. Paste the short file below into .gitignore at the root of your repo, then read why each line is there and which grey areas need a decision.

A Copy-Ready Python Gitignore File

This is the file we start every new Python project with. It's grouped by the tool that creates each file, so you can delete a block you don't need.

# Bytecode and compiled extensions
__pycache__/
*.py[cod]
*$py.class
*.so

# Packaging and build output
build/
dist/
*.egg-info/
.eggs/
wheels/

# Virtual environments
.venv/
venv/
env/

# Test, type-checker and linter caches
.pytest_cache/
.mypy_cache/
.ruff_cache/
.coverage
.coverage.*
htmlcov/

# Secrets and notebooks
.env
.ipynb_checkpoints/

Save it as .gitignore in the same folder as .git. Git then stops listing those paths in git status and won't stage them with git add .. Two rules catch people out. First, the file only affects untracked files, so anything you've already committed stays tracked. Second, a # starts a comment only at the beginning of a line, so never put a comment after a pattern.

In a src/ layout or a repo with several packages, one root file is usually enough, because patterns without a slash in the middle match at any depth. A .gitignore inside a subfolder also works, and its patterns apply relative to that folder.

Starting a fresh repo? Commit a README alongside this file. Our README Markdown guide covers what to put in it. For an open source project, add a LICENSE file too, as our MIT License guide shows.

Should venv and .venv Go in .gitignore?

Yes. A virtual environment holds every package you've installed, plus absolute paths that only work on your machine. Your teammates rebuild it from requirements.txt or pyproject.toml, so the environment itself never belongs in Git.

Newer tools already help here. Since Python 3.13, python -m venv writes a .gitignore inside the environment folder that ignores the whole directory, and --without-scm-ignore-files turns that off. The venv documentation lists both changes. uv's project .venv also ships with its own internal .gitignore.

So why does a gitignore for Python still list venv folders at all? Older Pythons, the virtualenv package and teammates who name their environment env or venv don't get that protection. Listing .venv/, venv/ and env/ costs nothing and covers every case.

Why Ignore __pycache__ and .pyc Files?

When you import a module, Python caches its compiled bytecode in a __pycache__ folder next to the source. A file named utils.py becomes something like __pycache__/utils.cpython-313.pyc, with your interpreter version in the name. Python rebuilds these files whenever the source changes, so committing them only adds noise and merge conflicts.

The rule that handles it is __pycache__/. The trailing slash limits it to directories, and it catches every __pycache__ folder in the tree. The other lines in that block work like this:

  • *.py[cod] matches .pyc and .pyo bytecode, plus .pyd extension modules on Windows. The square brackets match any one of the listed characters.
  • *$py.class catches the compiled files Jython produces.
  • *.so covers compiled C extensions you build locally on Linux and macOS.

GitHub's current template writes *.py[codz], which also matches .pyz files. Add the z if you build zipapps. For anything beyond these patterns, the git-scm gitignore reference documents the full syntax. Our gitignore format guide explains wildcards, negation and comments with examples.

Build Output and Tool Caches: dist/, .pytest_cache and More

Build tools and test runners both write files you regenerate on every run. Neither kind belongs in Git.

Packaging output: dist/, build/ and *.egg-info

Running python -m build writes a source archive and a wheel into dist/. Setuptools also creates a build/ staging folder and a yourpackage.egg-info/ metadata folder while it works. All three are generated from your source on every build.

Never commit them. A stale wheel in dist/ is easy to upload by accident, and *.egg-info folders go out of date the moment you change a dependency. The .eggs/ line catches eggs that older setuptools versions fetched during a build, and wheels/ is a common home for locally built wheels.

If you publish docs with MkDocs, add /site too. That's the folder mkdocs build writes, and our MkDocs Markdown post explains the build step.

Test, type-checker and linter caches

Every tool in a modern Python workflow keeps a cache in your project folder. Each one is local state that speeds up the next run, and none of it means anything on another machine.

  • .pytest_cache/ stores pytest's record of failed tests for --last-failed runs.
  • .mypy_cache/ holds mypy's incremental type-checking data.
  • .ruff_cache/ is Ruff's default cache directory.
  • .coverage is coverage.py's data file, and .coverage.* covers the extra files parallel runs write.
  • htmlcov/ is where coverage html puts its report by default.

Using tox or nox? Add .tox/ and .nox/. Hypothesis users need .hypothesis/ as well.

Keeping .env Secrets and Jupyter Checkpoints Out of Git

A .env file usually holds API keys and database passwords, which is why it sits in the ignore list. Commit a .env.example with placeholder values instead, so new contributors know which variables to set. Because .env matches only that exact name, .env.example stays visible without any extra rule. If you also keep files such as .env.local, add .env.* and then !.env.example to re-include the template.

Jupyter stores checkpoint copies of your notebooks in .ipynb_checkpoints/ folders next to them, so you can revert to the last saved version. They duplicate your work and change every time you save, so ignore them.

Ignoring a file doesn't remove it from history, though. If a real key was ever pushed, rotate it with the provider today. Cleaning the commit history is a separate job, and the old value may already be copied somewhere.

Should You Commit poetry.lock, uv.lock or Pipfile.lock?

For applications, commit the lock file. Poetry's basic usage docs tell you to commit poetry.lock so everyone installs the same versions, and uv says the same about uv.lock. GitHub's template agrees and notes these files are more commonly ignored for libraries. Its comments also point to a Pipenv issue recommending the same for Pipfile.lock.

The library case is a judgement call. Your users never install from your lock file, so a pinned file can hide a breaking upstream release from you. We prefer committing it anyway and refreshing it on a schedule, because a reproducible CI run makes failing tests much easier to trace.

What about .python-version? pyenv and uv both read it to pick an interpreter. Commit it when the whole team should use the same Python. Ignore it when it records one developer's local choice, which is common for libraries tested across several versions.

GitHub's Python Gitignore Template vs a Short File

GitHub maintains a much longer Python.gitignore template of more than 200 lines. Beyond the essentials, it covers Django's db.sqlite3, Flask's instance/, Scrapy, Sphinx's docs/_build/, PyInstaller, Celery, pdm, pixi, marimo and Streamlit's secrets.toml. It's also what GitHub offers when you pick Python in the new repository form.

Reach for GitHub's full Python gitignore when your project uses several of those frameworks or has many contributors with different setups. The short file wins when you want every line to be one you understand. Editor and OS files such as .vscode/ or .DS_Store aren't Python-specific, so many developers keep those in a personal global ignore file instead.

The short file has a limit, though. It doesn't know your framework, so a Django project still needs db.sqlite3 and media/ added by hand.

If you'd rather build the file than copy it, our .gitignore generator's Python template holds the same lines as the file above, plus GitHub's .Python line. It runs in your browser and opens with Node, Next.js, macOS and VS Code already ticked, so click Clear selection first. Then tick Python plus your operating system and editor, and copy or download the combined file into your repo yourself.

How to Untrack __pycache__ or .env Already Committed

Adding a pattern doesn't untrack a file Git already knows about. You have to remove it from the index first. The --cached flag keeps the file on your disk.

git rm -r --cached __pycache__
git rm --cached .env
git commit -m "Stop tracking cache and secrets"

The -r flag is needed for directories. If __pycache__ folders are scattered through your package, run git rm -r --cached . followed by git add . to restage everything against your new rules.

Then confirm a rule matches:

git check-ignore -v .env

This prints the source file, line number and pattern that matched, such as .gitignore:28:.env followed by the path. No output means nothing matched. It also prints nothing for files that are still tracked, so run it after the git rm --cached step. To see everything your rules currently hide, run git status --ignored and scan the list for anything you meant to commit.

A good Python gitignore is short enough to read and specific enough to keep caches, environments and secrets out of your history. Start with the file at the top, add your framework's files, and commit your lock file if you're shipping an application. Then write the project's README in the editor, which is free and runs in your browser with no account needed. If you're also rendering Markdown docs from Python, see Python Markdown.