Repository navigation
Add a .gitignore file to each __pycache__ folder #141081
Description
Activity
Is not
__pycache__in a single top-level.gitignorefile enough?Is not
__pycache__in a single top-level.gitignorefile 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.
Reacted by Mikhail EfimovMy 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
venvmodule 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
venvmodule when we added the same thing there?We added a
--without-scm-ignore-filesflag and ascm_ignore_filesparameter and documented those:Although the What's New is the best overview:
Did we update any docs for the
venvmodule 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":
Perhaps this would be a good place to put it:
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.
Reacted by Maxim Martynov and Gregory P. SmithIf 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.
17 remaining items
I think we are overthinking it. The content of
__pycache__is an implementation detail. It was already changed in the past (from.pycand.pyoto.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).
Reacted by Zachary Ware, Stan Ulbrych, Brett Cannon, Bartosz Sławecki, Gregory P. Smith and Hugo van KemenadeI 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?
Reacted by Hugo van Kemenadeyeah lets just see how it goes.
Reacted by Hugo van KemenadeThis 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.gitignorefile for Git to ignore their contents
Thanks all!
Reacted by Mikhail EfimovThanks all indeed!
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.gitignoreso the dir removal fails.#142745 is a possible fix to not add
.gitignoreinsite-packagesdirs, and let the package managers handle those.However, it hardcodes
site-packages. We should maybe usesysconfig.get_path('purelib')instead in case the user has reconfigured to use something else, such asdist-packagesin Ubuntu, but we can'timport sysconfigin_bootstrap_external.pybecause 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.
Reacted by Stan UlbrychBut 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?
- added a commit that references this issue
on Dec 15, 2025
Feature or enhancement
Proposal:
When creating a
__pycache__folder, add a.gitignorefile with the contentI've seen this pattern appear in a few places (coverage.py's
htmlcovfolder,.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
.gitignorefile to__pycache__folders #141162.gitignorefile to__pycache__folders (#141162)" #142758