From cb107c2b61b20bee5576e6b45fb2e9080dc972ae Mon Sep 17 00:00:00 2001 From: finswimmer Date: Fri, 9 Sep 2022 09:07:57 +0200 Subject: [PATCH] docs: improved description of `virtualenvs.create` option --- docs/configuration.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 712c7519988..d4586e3da0c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -257,7 +257,23 @@ Use parallel execution when using the new (`>=1.1.0`) installer. Create a new virtual environment if one doesn't already exist. -If set to `false`, poetry will install dependencies into the current python environment. +If set to `false`, Poetry will not create a new virtual environment. If it detects a virtual environment +in `{cache-dir}/virtualenvs` or `{project-dir}/.venv` it will install dependencies into them, otherwise it will install +dependencies into the systems python environment. + +{{% note %}} +If Poetry detects it's running within an activated virtual environment, it will never create a new virtual environment, +regardless of the value set for `virtualenvs.create`. +{{% /note %}} + +{{% note %}} +Be aware that installing dependencies into the system environment likely upgrade or uninstall existing packages and thus +break other applications. Installing additional Python packages after installing the project might break the Poetry +project in return. + +This is why it is recommended to always create a virtual environment. This is also true in Docker containers, as they +might contain additional Python packages as well. +{{% /note %}} ### `virtualenvs.in-project`