Question
Poetry virtualenvs.in-project configuration and repository exclusion boundaries
Mira Nova
0 reputation · 05 Feb 2020, 14:30 UTC
93.9K views
Loading…
0 reputation · 05 Feb 2020, 14:30 UTC
Poetry's virtualenvs.in-project setting places the managed environment inside the project directory, which simplifies container builds and removes dependence on a shared cache path. The tradeoff is that the environment now sits within the source tree, where standard version-control and packaging workflows may treat it as project content unless explicitly excluded.
The uncertainty is where Poetry's responsibility ends and the user's begins. The setting changes only the environment's storage location; it does not alter how version-control or container build systems treat that directory. Exclusion therefore depends entirely on project-level ignore rules, and an incomplete configuration can expose the environment path, installed packages, and absolute interpreter references.
For teams adopting this setting across multiple projects, the open question is whether Poetry offers any configuration guardrails to warn about or prevent unignored in-project environments, or whether every exclusion must be managed manually per repository. Because guardrail behavior may differ across Poetry releases, the exact boundary should be confirmed against the installed version.
Does Poetry provide any built-in detection for unexcluded in-project virtualenv directories? If not, what is the recommended configuration pattern for enforcing exclusion across repositories without relying on global Git templates? Should virtualenvs.in-project be avoided in favor of centralized cache storage when the project directory is synced to public or shared locations?
35275 reputation · 05 Feb 2020, 22:46 UTC
No. Poetry does not provide built-in detection for unexcluded in-project virtualenv directories. Enabling virtualenvs.in-project changes only where Poetry creates and resolves the environment; it does not write ignore rules, warn about uncommitted environments, or prevent version-control systems from tracking the directory. Exclusion is a project-level concern that Poetry delegates entirely to the user.
Confirmed across Poetry's 1.x and 2.x lines: when virtualenvs.in-project is true, Poetry places the environment in a project-local .venv/ directory and reports its path via poetry env info --path. The absence of automatic .gitignore management is long-standing behavior. However, whether any minor release emits warnings about unexcluded environments is version-dependent; treat any claim of a guardrail as unverified until confirmed against your installed release.
Because Poetry offers no native cross-repository enforcement, the exclusion rule must live in the repository itself. Global Git templates and global gitignore files are outside Poetry's control and may not apply to CI runners or container builds, so they are not a reliable boundary.
poetry.venv/ to the repository's .gitignore before the first poetry install.git check-ignore -v .venv/; a non-zero exit means the path is not ignored.git ls-files .venv/ returns any output, catching accidental git add -f or stale tracking.When a project directory is synced to public or shared locations, centralized cache storage is the safer default. An in-project .venv/ contains installed packages, compiled extensions, and absolute interpreter references in files such as pyvenv.cfg and activation scripts. If ignore rules are incomplete—or if the sync target does not respect .gitignore—that content can leak. Centralized cache storage keeps the environment outside the tree, so no exclusion rule is required.
Keep virtualenvs.in-project when the benefit is concrete, such as container builds that copy the project directory or IDE tooling that expects a local environment, and only after the ignore rule is verified in the repository itself.
poetry config --list | grep virtualenvs.in-project
poetry env info --path
git check-ignore -v .venv/
git ls-files .venv/The first two commands confirm Poetry's view of the configuration and resolved path. The last two confirm the repository's view. If git check-ignore exits non-zero, the environment is exposed regardless of Poetry's settings.
One missing detail would change the recommendation: whether your sync or deployment target respects .gitignore. If it does not, even a correct repository-local rule will not prevent leakage, and centralized cache storage becomes the stronger choice. Which sync mechanism are you using?
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.