install: make --sync compatible with virtualenvs.options.system-site-packages = true

[radoering]

Pull Request Check List

More or less required for #9855

Without this fix, we try to uninstall untracked system site packages when running poetry install --sync.

• Added tests for changed code.
• Updated documentation for changed code.

[abn]

This seems to have a side-effect when poetry installs a managed package to system-site. It does also removes previously installed packages.

podman run --rm -i --entrypoint bash python:3.13 <<EOF
set -xe
python -m pip install -q --root-user-action=ignore --disable-pip-version-check pipx
pipx install --global -q git+https://github.com/python-poetry/poetry.git@refs/pull/9863/head
poetry new foobar
pushd foobar
# we are doing this here to test a specific use case, do not reuse in your environment
poetry config virtualenvs.create false
poetry add pycowsay
poetry remove pycowsay
poetry install --sync
EOF

+ python -m pip install -q --root-user-action=ignore --disable-pip-version-check pipx
+ pipx install --global -q git+https://github.com/python-poetry/poetry.git@refs/pull/9863/head
creating virtual environment...
creating shared libraries...
upgrading shared libraries...
determining package name from 'git+https://github.com/python-poetry/poetry.git@refs/pull/9863/head'...
creating virtual environment...
installing poetry from spec 'git+https://github.com/python-poetry/poetry.git@refs/pull/9863/head'...
done! ✨ 🌟 ✨
  installed package poetry 2.0.0.dev0, installed using Python 3.13.0
  These apps are now globally available
    - poetry
+ poetry new foobar
Created package foobar in foobar
+ pushd foobar
/foobar /
+ poetry config virtualenvs.create false
+ poetry add pycowsay
Skipping virtualenv creation, as specified in config file.
Using version ^0.0.0.2 for pycowsay

Updating dependencies
Resolving dependencies...

Package operations: 1 install, 0 updates, 0 removals

  - Installing pycowsay (0.0.0.2)

Writing lock file
+ poetry remove pycowsay
Skipping virtualenv creation, as specified in config file.
Updating dependencies
Resolving dependencies...

Package operations: 0 installs, 0 updates, 1 removal

  - Removing pycowsay (0.0.0.2)

Writing lock file
+ poetry install --sync
Skipping virtualenv creation, as specified in config file.
Installing dependencies from lock file

Package operations: 0 installs, 0 updates, 6 removals

  - Removing argcomplete (3.5.1)
  - Removing click (8.1.7)
  - Removing packaging (24.2)
  - Removing pipx (1.7.1)
  - Removing platformdirs (4.3.6)
  - Removing userpath (1.9.2)

Installing the current project: foobar (0.1.0)

[radoering]

This seems to have a side-effect when poetry installs a managed package to system-site. It does also removes previously installed packages.

This PR does not change anything about that. You can reproduce the same behavior with Poetry 1.8.4.

If you replace poetry config virtualenvs.create false with poetry config virtualenvs.options.system-site-packages true you will see what this PR changes.

[abn]

You are right. Looks like the removal of system packages when create env is false is an existing issue. I have verified that that this change does functionally fix --sync from being too eager in removals when a virtualenv is used with system site packages.