Document what happens when venv is run using existing directory

[piotr-kubiak]

Documentation

Please consider specifying the behavior of venv module when the ENV_DIR already exists, and/or is not empty and/or contains an existing virtual environment. Currently the docs mentions only: “running this command creates the target directory”, and “creates” implies the command should be executed when ENV_DIR is not present [1].

However, I am able to run python -m venv .venv twice, and there is no error. There is no mention in the docs what happens when the directory is already there. Does venv skips creation of virtual environment? Does it try to create it anyways? What if ENV_DIR content is already a virtual environment? What if it is somewhat broken, does venv try to “fix” it?

[1] On the other hand, there are options --clear, --update, --update-deps, and those imply the ENV_DIR should be present. But it contradicts the previous assumption.

[hugovk]

Hello, the same paragraph in the docs ends with:

If an existing directory is specified, it will be re-used.

https://docs.python.org/3/library/venv.html#creating-virtual-environments

How does that sound? To me, re-use implies no error and no recreation.

[piotr-kubiak]

How does that sound? To me, re-use implies no error and no recreation.

The problem is with what "re-use" means.
The more obvious cases:

• How re-using empty directory works?
• How re-using directory that already contains virtual environment works?

The more complicated ones:

• How re-using directory that is not empty, but contains something other than virtual environment?
• How re-using directory that contains virtual environment created with other python version works?
• How re-using directory that contains virtual environment with missing "site-packages" directory works?

And the list goes.