Skip to content

✨ feat(create): skip distutils hook on Python 3.10+ - #3184

Merged
gaborbernat merged 2 commits into
pypa:mainfrom
gaborbernat:feat/conditional-virtualenv-patch
Jul 6, 2026
Merged

gaborbernat merged 2 commits into
pypa:mainfrom
gaborbernat:feat/conditional-virtualenv-patch

Conversation

@gaborbernat

Copy link
Copy Markdown
Contributor

virtualenv installs a _virtualenv.{py,pth} import hook into every environment to stop distutils install config keys (prefix, install_purelib, and friends from ~/.pydistutils.cfg or a project setup.cfg) from redirecting package installs outside the environment. As #3181 tracks, that guard no longer earns its keep on modern Python. Since 3.10 pip ignores those keys by default, and both setuptools and CPython's vendored distutils drop them too. What survives is cost. The .pth runs import _virtualenv on every interpreter startup, which imports contextlib and adds about 2ms (measured in the issue).

This gates hook installation on the target interpreter version, so environments for Python 3.10 and later skip the hook and its startup import. The cutoff avoids a blanket removal for one reason: the last pip release supporting Python 3.9 still needs the workaround below 3.10, so 3.9 environments keep the hook. Once virtualenv drops 3.9, install_patch and _virtualenv.py can go for good.

Nothing changes for 3.9 or for the escape-prevention guarantee itself, since pip on 3.10+ keeps installs inside the environment without our hook. Closes #3181.

The _virtualenv.{py,pth} import hook exists to stop distutils install
config keys from redirecting package installs outside the virtual
environment. Since 3.10 pip ignores those keys by default, and setuptools
and CPython's vendored distutils drop them too, so the hook guards
against nothing while adding ~2ms to every interpreter startup by
importing contextlib.

Gate installation on the target interpreter version so 3.10+ venvs skip
the hook and its startup cost, while 3.9 keeps it: the last pip that
supports 3.9 still needs the workaround for Python below 3.10. When 3.9
support is dropped the hook can be removed entirely.

Closes pypa#3181
@gaborbernat
gaborbernat enabled auto-merge (squash) July 6, 2026 22:31
@gaborbernat
gaborbernat disabled auto-merge July 6, 2026 22:47
@gaborbernat
gaborbernat merged commit 04ff756 into pypa:main Jul 6, 2026
53 checks passed
@gaborbernat
gaborbernat deleted the feat/conditional-virtualenv-patch branch July 6, 2026 22:54
konsti-openai added a commit to konsti-openai/rules_py that referenced this pull request Jul 20, 2026
Stop materializing and importing the virtualenv distutils shim for Python 3.10+, where pip and setuptools already ignore the affected install configuration. Keep the shim for Python 3.9 and move the rules_py-specific PATH setup into the existing venv .pth so console scripts remain discoverable.

Match the upstream changes:
pypa/virtualenv#3184
astral-sh/uv#20222
jbedard pushed a commit to konsti-openai/rules_py that referenced this pull request Aug 13, 2026
Stop materializing and importing the virtualenv distutils shim for Python 3.10+, where pip and setuptools already ignore the affected install configuration. Keep the shim for Python 3.9 and move the rules_py-specific PATH setup into the existing venv .pth so console scripts remain discoverable.

Match the upstream changes:
pypa/virtualenv#3184
astral-sh/uv#20222
jbedard added a commit to aspect-build/rules_py that referenced this pull request Aug 13, 2026
This is a port of pypa/virtualenv#3184 and
astral-sh/uv#20222, which removed the distutils
hack recently. Removing this brings venv creation in line with
virtualenv and uv again and improves Python startup perf.

This is the conservative version of this change. The workaround is only
required in an obscure setup where you have the bogus ancient
configuration file in the current directory when performing operations.
If we can safely assume that bazel users don't do that, we can remove
the two files entirely.

---

### Changes are visible to end-users: yes

- Searched for relevant documentation and updated as needed: yes
- Breaking change (forces users to change their own code or config): yes
- Suggested release notes appear below: yes

Python 3.9 venvs keep the shim.

Python 3.10+ targets:
* `_virtualenv.py` / `_virtualenv.pth` are no longer created, and the
venv bin/ PATH setup moved into the main `<name>.pth`.
* Code importing `_virtualenv` directly (e.g. as a path anchor) must use
another anchor such as sys.prefix.
* On 3.10+, a direct legacy `setup.py` install into a built venv with
underscore-form `[install]` keys (`install_purelib`, …) is no longer
stripped and can install outside the venv. Installing into a built venv
at runtime is not a supported rules_py workflow.

### Test plan

- Covered by existing test cases

---------

Co-authored-by: Jason Bedard <jason+github@jbedard.ca>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Is _virtualenv.{py,pth} still required

1 participant