From 0b1c5b91de68684d31eb36ef99093b6b78a888b3 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..c243fbfbf13 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`