Add a .gitignore file to each __pycache__ folder

Feature or enhancement

Proposal:

When creating a __pycache__ folder, add a .gitignore file with the content

# Created by CPython
*

I've seen this pattern appear in a few places (coverage.py's htmlcov folder, .venv, .pytest_cache) and it saves projects from having to add such things to their main .gitignore.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

Is not __pycache__ in a single top-level .gitignore file enough?

Similarly, we added a .gitignore to venv dirs in 3.13: #83417.

Is not __pycache__ in a single top-level .gitignore file enough?

But that would have to be added by every user for every repo.

I would like the repo .gitignore to be about artifacts of the software in the repo, not artifacts of tools if we can avoid it.

Creating it ourselves also sends a clear signal that you really shouldn't be checking this stuff in.

My biggest question is how do we document this (I'm sure someone somewhere is checking in their __pycache__ files on purpose)? I'm assuming we will tweak this as we just deem reasonable based on whatever VCS is most popular at the time, but we should be clear in the docs that what's supported can change and there won't be any warning beyond What's New.

Did we update any docs for the venv module when we added the same thing there?

Is __pycache__ documented at all? Wherever that is, is where the docs should be updated for this.

Did we update any docs for the venv module when we added the same thing there?

We added a --without-scm-ignore-files flag and a scm_ignore_files parameter and documented those:

Although the What's New is the best overview:

https://docs.python.org/3/whatsnew/3.13.html#venv

Did we update any docs for the venv module when we added the same thing there?

Is __pycache__ documented at all? Wherever that is, is where the docs should be updated for this.

It's mentioned on a dozen pages but doesn't seem to have its own "home":

https://docs.python.org/3/search.html?q=__pycache__

Perhaps this would be a good place to put it:

https://docs.python.org/3/tutorial/modules.html#compiled-python-files

There's a PR up at #141162.

This sounds like unnecessary noise for things like container images. There are tons of repository templates including in GitHub which will initialize your repo with top-level .gitignore for Python.

If this is done, please make it opt-outable at least. I am quite surprised also to hear that venv went ahead with this feature.

It's opt-out for venv using --without-scm-ignore-files:

https://docs.python.org/3/library/venv.html#cmdoption-venv-without-scm-ignore-files

I was referring to if adding this became a Python default, not just venv. There should really be an opt-out.

I was referring to if adding this became a Python default, not just venv. There should really be an opt-out.

This is a bit off-topic for this issue. If you want to propose reverting the default behaviour for venv then please open another issue.

I think we are overthinking it. The content of __pycache__ is an implementation detail. It was already changed in the past (from .pyc and .pyo to .cpython-315.opt-2.pyc) and depends on the Python version, so if you use the same source tree with different Python versions it can be full of abandoned stuff). Simply, either add .gitignore, or don't.

I don't think adding it will help much, but it will not harm. If you worry about disk space, you should seriously consider precompiling bytecode and packing it in a zip file (even without compression it will save a lot of space for small files).

I think we are overthinking it.

I think I agree.

Any core devs against merging w/o an opt-out and seeing how it goes during the alpha and beta phases?

yeah lets just see how it goes.

@hugovk

and have release manager @hugovk promote it in release notes asking people to pipe up if it causes problems and make the final call based on any feedback before the RC phase.

gh-141081: Add a `.gitignore` file to `__pycache__` folders (#141162)

This will be in tomorrow's 3.15.0a3, is called out in What's New's release highlights and I'll also put this in the release notes:

__pycache__ directories now contain a .gitignore file for Git to ignore their contents

Thanks all!

Thanks all indeed!

@encukou

Re-opening.

Buildbots failed after merging the PR: #141162 (comment)

test_with_pip (test.test_venv.EnsurePipTest.test_with_pip) ... FAIL

======================================================================
FAIL: test_with_pip (test.test_venv.EnsurePipTest.test_with_pip)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/buildbot/buildarea/3.x.itamaro-centos-aws.nogil/build/Lib/test/test_venv.py", line 1047, in test_with_pip
    self.do_test_with_pip(False)
    ~~~~~~~~~~~~~~~~~~~~~^^^^^^^
  File "/home/buildbot/buildarea/3.x.itamaro-centos-aws.nogil/build/Lib/test/test_venv.py", line 1023, in do_test_with_pip
    self.assert_pip_not_installed()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/home/buildbot/buildarea/3.x.itamaro-centos-aws.nogil/build/Lib/test/test_venv.py", line 906, in assert_pip_not_installed
    self.assertEqual(out.strip(), "OK")
    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
AssertionError: '' != 'OK'
+ OK

The problem was that when pip uninstalls itself, it removes its own files, and then tries to remove empty directories like __pycache__. But __pycache__ contains our .gitignore so the dir removal fails.

#142745 is a possible fix to not add .gitignore in site-packages dirs, and let the package managers handle those.

However, it hardcodes site-packages. We should maybe use sysconfig.get_path('purelib') instead in case the user has reconfigured to use something else, such as dist-packages in Ubuntu, but we can't import sysconfig in _bootstrap_external.py because it's too early and can result in a circular import.

But as @encukou asks:

More generally: how can you tell what “manages” a given directory? I don't really have an answer, I'm afraid.

Thoughts?

RM hat: we may need to revert this for tomorrow's a3 so we have more time for this.

Revert "pythongh-141081: Add a `.gitignore` file to `__pycache__` fol…

But as @encukou asks:

More generally: how can you tell what “manages” a given directory? I don't really have an answer, I'm afraid.

Thoughts?

At what directory level? Virtual environment (which Alyssa has an idea)? All installed projects? Each installed project?

gh-141081: Revert "Add a `.gitignore` file to `__pycache__` folders (#…

pythongh-141081: Add a `.gitignore` file to `__pycache__` folders (py…

pythongh-141081: Revert "Add a `.gitignore` file to `__pycache__` fol…

Navigation Menu

Repository navigation

Add a .gitignore file to each pycache folder #141081

Feature or enhancement

Proposal:

Has this already been discussed elsewhere?

Links to previous discussion of this feature:

Linked PRs

17 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Add a .gitignore file to each __pycache__ folder #141081

Description

Feature or enhancement

Proposal:

Has this already been discussed elsewhere?

Links to previous discussion of this feature:

Linked PRs

Activity

serhiy-storchaka commented on Nov 6, 2025

hugovk commented on Nov 6, 2025

gvanrossum commented on Nov 6, 2025

zware commented on Nov 6, 2025

brettcannon commented on Nov 6, 2025

gvanrossum commented on Nov 6, 2025

hugovk commented on Nov 7, 2025

nanonyme commented on Nov 7, 2025

nanonyme commented on Nov 7, 2025

hugovk commented on Nov 7, 2025

nanonyme commented on Nov 7, 2025

brettcannon commented on Nov 7, 2025

17 remaining items

serhiy-storchaka commented on Dec 8, 2025

brettcannon commented on Dec 12, 2025

gpshead commented on Dec 13, 2025

gpshead commented on Dec 13, 2025

hugovk commented on Dec 15, 2025

gvanrossum commented on Dec 15, 2025

hugovk commented on Dec 15, 2025

brettcannon commented on Dec 15, 2025

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Add a .gitignore file to each pycache folder #141081