venv overwrites existing .gitignore

[0xUnicorn]

Bug report

Bug description

I cloned a github project with an existing .gitignore file.
I created a new python venv inside the cloned project using python3 -m venv .venv .
After creating the new venv, I see that the .gitignore file has been modified.

diff --git a/.gitignore b/.gitignore
index d0258704..f514b74c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,17 +1,2 @@
-.dev
-.idea/
-.hypothesis/
-__pycache__/
-db.sqlite3
-*.sw*
-*.pyc
-venv/
-.venv/
-environment_settings.py
-elm-stuff/
-.coverage
-media
-docker/.env
-node_modules
-package-lock.json
-.sass-cache
+# Created by venv; see https://docs.python.org/3/library/venv.html
+*

I found this documentation on the mentioned url added to the .gitignore file:

Changed in version 3.13: venv now creates a .gitignore file for Git by default.

Environment

• Arch linux 6.14.9
• Python 3.13.3

Expected behaviour

I would expect it to not overwrite an existing .gitignore file, so it only creates it if it isnt present already.

Update

Using python3 -m venv .venv works as expected, but I did python3 -m venv .venv . (trailing dot) which creates a folder with a new venv named .venv, but also creates a venv inside the existing folder ., and that's when it overwrites the .gitignore

Please let me know if I'm missing some details or you need further testing for triage the issue.

CPython versions tested on:

3.13

Operating systems tested on:

Linux

Linked PRs

• gh-135604: Append to .gitignore instead of overwriting it #139130

[skirpichev]

python3 -m venv .venv . - Ah, I guess the . was a typo, but it changed things.

Looking on the code, it indeed creates .gitignore unconditionally. Though, I'm not sure if this is a bug or a feature. I would rather create a dedicated directory for new venv.

CC @brettcannon

[brettcannon]

I created a new python venv inside the cloned project using python3 -m venv .venv .

First thing to say is please don't do this. The docs specifically say, "You don’t place any project code in the environment."

I'm not sure if this is a bug or a feature.

So the docs do not say creation is conditional, so I wouldn't say it's a bug, but potentially unexpected behaviour.

I would be fine with stronger wording in the docs if that would help. It could be updated to say the .gitignore file is unconditionally created. We could also consider making it more obvious that you should not put your code inside your virtual environment.

@vsajip do you have an opinion?

[0xUnicorn]

I created a new python venv inside the cloned project using python3 -m venv .venv .

First thing to say is please don't do this. The docs specifically say, "You don’t place any project code in the environment."

I'm not sure if this is a bug or a feature.

So the docs do not say creation is conditional, so I wouldn't say it's a bug, but potentially unexpected behaviour.

I would be fine with stronger wording in the docs if that would help. It could be updated to say the .gitignore file is unconditionally created. We could also consider making it more obvious that you should not put your code inside your virtual environment.

@vsajip do you have an opinion?

Using python3 -m venv .venv . wasn't intentionally, I have the first part as an alias, and I added . at the end by a mistake. Which lead to unexpected behaviour.

Changing the line

Changed in version 3.13: venv now creates a .gitignore file for Git by default.

to

Changed in version 3.13: venv now unconditionally creates a .gitignore file for Git by default, inside the ENV_DIR.

Would be a more explicit description of the intended behaviour.

[Zheaoli]

I think this is not about the .gitignore or the docs problem.

The core issue is the python -m venv allow developer create more than one venv. And . is just one of the directories. I think maybe we can do following things

1. logging warning if more than one directory here
2. logging warning if there is .gitignore existed

[brettcannon]

1. logging warning if more than one directory here

But that's a legitimate use, so warning about it doesn't seem fair to those who want that workflow.

2. logging warning if there is .gitignore existed

Maybe, although the warning should probably be more along the lines of, "a directory already exists".

But the issue with any warning is venv is a library and a CLI, and the CLI just calls the API. So where do you put the warning? You probably don't want it in the API, but the CLI is just a thin wrapper around the API.

You could maybe put it in:

cpython/Lib/venv/__init__.py

Lines 686 to 687 in a8ec511

	for d in options.dirs:
	builder.create(d)

but only if you aren't doing an in-place upgrade. But I would still want @vsajip to weigh in before suddenly adding any output to the CLI.

[julianghionoiu]

I've encountered the same issue during an coding interview setup where I am dealing with developers who might not know what the best practice is.
In this particular case they've run python3 -m venv . which had the side-effect of ignoring all files in the working directory.

I think initialising a venv in a folder where there is already a .gitignore is almost always a user error and should be prevented.

[vsajip]

I've encountered the same issue during an coding interview setup

I'm not sure we need to go out of our way in code changes to overly cater to inexperienced developers making mistakes - they are always going to able to do something which is problematic, and it seems a slippery slope. For example, initialising a venv in a user's home directory would be problematic too.

I'm fine with documentation updates to make things clearer.