PEP 796: relative virtual environments, initial draft #4476

rickeylev · 2025-06-30T17:57:23Z

Basic requirements (all PEP Types)

Standards Track requirements

Work towards python/cpython#136051

📚 Documentation preview 📚: https://pep-previews--4476.org.readthedocs.build/

.github/CODEOWNERS

hugovk · 2025-06-30T19:11:53Z

Hello, before we go any further with this PR, has the idea been discussed on Discourse?

And after that we'll need a sponsor before assigning the PEP number, do you have one yet? Let's unassign 796 for now.

Please see:

rickeylev · 2025-06-30T20:42:41Z

Thanks @hugovk and @StanFromIreland for the early review. I used a draft PR to see the CI results to further clean it up -- my apologies for wasting some of your time, but thank you regardless.

discussed on Discourse?

Yes: https://discuss.python.org/t/making-venvs-relocatable-friendly/96177

The criteria of "discussed enough with enough support" is vague, but what gave me enough confidence to begin a PEP and start a (draft) PR at this point was:

The thread didn't go totally off the rails (i.e. voracious disapproval)
Positive statements from @ncoghlan in https://discuss.python.org/t/making-venvs-relocatable-friendly/96177/21 and gh-135773: have pyvenv.cfg without home key anchor a venv and deduce home cpython#135831 (comment)

Sponsor needed to assign number

Thanks for clarifying that part! Yes, finding a sponsor is my next big step.

hugovk · 2025-06-30T21:30:41Z

I used a draft PR to see the CI results to further clean it up

Tip: you can enable GitHub Actions at https://github.com/rickeylev/peps/actions and run the CI on your fork.

Yes, finding a sponsor is my next big step.

Good luck!

…-venv section

rickeylev · 2025-07-02T03:20:04Z

Brief update:

I have a sponsor: @ncoghlan has offered to sponsor this PEP. I've updated the PEP text accordingly.

So, IIUC, next steps are:

Sponsor formally confirms they're a sponsor
Sponsor approves this PR

I'm not entirely sure on process, so I'll just leave this PR in draft state until those are done / imminent.

ncoghlan · 2025-07-02T07:58:06Z

Confirming my sponsorship (the parts of the proposal I felt were at best premature, and potentially entirely infeasible, have been removed).

Completing a pre-publication review now.

ncoghlan

Generally looks good to me. Thanks for writing this up!

Assorted more detailed comments inline.

peps/pep-0796.rst

Co-authored-by: Alyssa Coghlan <[email protected]>

hugovk · 2025-07-02T17:56:56Z

Thanks @ncoghlan for sponsoring and approving! Let's continue with PEP number 796.

Next steps: a PEP editor to review, then merge, and then the PEP discussion can be opened for this proposal.

peps/pep-0796.rst

Co-authored-by: Alyssa Coghlan <[email protected]>

zanieb · 2025-07-06T23:21:08Z

peps/pep-0796.rst

+
+Second, such relative paths are a building block to enable portable virtual
+environments, i.e. copying a virtual environment as-is between hosts of
+compatible platforms. Portable venvs are appealing because virtual environments


I wouldn't abbreviate here if you aren't elsewhere

Suggested change

compatible platforms. Portable venvs are appealing because virtual environments

compatible platforms. Portable virtual environments are appealing because virtual environments

zanieb · 2025-07-06T23:22:12Z

peps/pep-0796.rst

+benefits:
+
+* The closer the development environment is to the non-development environment,
+  the more reliable software can be achieved, and the easier it is to reproduce


I think you may want to rephrase "the more reliable software can be achieved", I find the meaning a bit confusing and it's used both here and in the next bullet?

zanieb · 2025-07-06T23:25:34Z

peps/pep-0796.rst

+still retain predictable and reliable behavior. Thus, the absolute path
+requirement should be relaxed and relative path behavior allowed and defined.
+
+Second, such relative paths are a building block to enable portable virtual


It'd be nice to hear more about why and how a relative path makes the virtual environment more portable. A Python installation will still need to exist in a specific location on the new host, right? Is the pitch for a relative path that you'd copy a virtual environment and the Python installation together?

Yep, that's the use case, although even the "copying" may be virtual - while an app embedding a single Python runtime and basing multiple virtual environments on it getting installed to different locations is one possibility, other potential scenarios would be a mounted parent folder in a container, or a mounted network drive on a host.

The key is that the position of the venv and its base runtime relative to each other is consistent, but the path prefix leading to their common parent folder may vary across systems.

hugovk · 2025-07-11T14:50:34Z

peps/pep-0796.rst

+.. highlight:: rst
+


Let's remove this, it's the syntax highlighter used for code blocks (default Python) and there aren't any code blocks here.

Suggested change

.. highlight:: rst

hugovk · 2025-07-11T15:04:52Z

peps/pep-0796.rst

+When the virtual environment doesn't require modifications to be usable, it
+also allows more advanced deployment mechanisms, e.g. remote mounting and
+caching of artifacts. While this PEP on its own isn't sufficient to enable
+that, it allows tools like ``bazel`` or ``venvstacks`` to more easily prepare


Suggested change

that, it allows tools like ``bazel`` or ``venvstacks`` to more easily prepare

that, it allows tools like Bazel or venvstacks to more easily prepare

hugovk · 2025-07-11T15:07:59Z

peps/pep-0796.rst

+(``bazel``, omitting the ``home`` key entirely to trigger an implementation
+dependent fallback to resolving via a symlinked interpreter binary on
+non-Windows systems) or by requiring a post-installation script to be executed
+after the environment is placed in its target location (``venvstacks``).


Suggested change

(``bazel``, omitting the ``home`` key entirely to trigger an implementation

dependent fallback to resolving via a symlinked interpreter binary on

non-Windows systems) or by requiring a post-installation script to be executed

after the environment is placed in its target location (``venvstacks``).

(Bazel, omitting the ``home`` key entirely to trigger an implementation

dependent fallback to resolving via a symlinked interpreter binary on

non-Windows systems) or by requiring a post-installation script to be executed

after the environment is placed in its target location (venvstacks).

hugovk · 2025-07-11T15:08:41Z

peps/pep-0796.rst

+* ``subdir/whatever/bin`` (a directory within the virtual environment).
+* ``./subdir/whatever/bin`` (same as above)
+* ``../../../../../elsewhere/runtime/bin`` (a directory outside the virtual
+  environment).


Suggested change

* ``subdir/whatever/bin`` (a directory within the virtual environment).

* ``./subdir/whatever/bin`` (same as above)

* ``../../../../../elsewhere/runtime/bin`` (a directory outside the virtual

environment).

* ``subdir/whatever/bin`` (a directory within the virtual environment)

* ``./subdir/whatever/bin`` (same as above)

* ``../../../../../elsewhere/runtime/bin`` (a directory outside the virtual

environment)

hugovk · 2025-07-11T15:10:58Z

peps/pep-0796.rst

+Tools that work around the absolute ``home`` key limitation the way ``bazel``
+and ``venvstacks`` currently do (omitting the ``home`` key, or editing it after


Suggested change

Tools that work around the absolute ``home`` key limitation the way ``bazel``

and ``venvstacks`` currently do (omitting the ``home`` key, or editing it after

Tools that work around the absolute ``home`` key limitation the way Bazel

and venvstacks currently do (omitting the ``home`` key, or editing it after

hugovk · 2025-07-11T15:11:34Z

peps/pep-0796.rst

+paths.
+
+A proof-of-concept of this is implemented in
+`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__


Suggested change

`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__

`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.

hugovk · 2025-07-11T15:12:38Z

peps/pep-0796.rst

+  host-relocatable virtual environments.
+* `rules_py <https://github.com/aspect-build/rules_py>`__: implements
+  host-relocatable virtual environments.
+* `python-build-standalone <https://github.com/astral-sh/python-build-standalone>`__:


Put something after the colon? Or delete the colon?

Suggested change

* `python-build-standalone <https://github.com/astral-sh/python-build-standalone>`__:

* `python-build-standalone <https://github.com/astral-sh/python-build-standalone>`__

hugovk · 2025-07-11T15:13:33Z

peps/pep-0796.rst

+  A relocatable Python runtime.
+* `PoC for relative home in Python startup <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__
+* `Python Ideas "Making venvs relocatable friendly" discussion <https://discuss.python.org/t/making-venvs-relocatable-friendly/96177>`__
+* `GH-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__


Convention is lowercase for issue, uppercase for PR:

Suggested change

* `GH-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__

* `gh-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__

rickeylev added 16 commits June 27, 2025 21:08

initial file

ceeaa3b

add some core content

d0a9289

rename to motivation

41d2ea8

note it enables more advanced optimizations

65a415c

add foot notes, relocatable term section, links

4175b20

update discussion, sponsor headers to pending

bbc85b7

rst fixups

a0c2529

fixup italics

8e6e21e

rename to relative-venv

37202ca

clarify advanced deployment options, reflow some text

b81c50f

add specification, rationale section; doc why env vars arent an option

55a5e28

also mention curdir syntax handling

e09b00d

update some todo text

c7a6a9b

update codeowners

bc1ffbd

add initial discussion footnote link

2301d2a

add fr footnote

e14b01f

rickeylev mentioned this pull request Jun 30, 2025

Support relative home in pyvenv.cfg (host-relocatable venv) python/cpython#136051

Open

StanFromIreland reviewed Jun 30, 2025

View reviewed changes

.github/CODEOWNERS Outdated Show resolved Hide resolved

hugovk added the DO-NOT-MERGE label Jun 30, 2025

hugovk changed the title ~~PEP 796: relative virtual environments, initial draft~~ PEP xxx: relative virtual environments, initial draft Jun 30, 2025

revert codeowners change

175f378

rickeylev added 6 commits July 1, 2025 18:17

remove packaging-related specs

31cb756

fix lint errors with headers

cd46f4d

set sponsor

b532f5c

set sponsor as codeowner

99434fc

clarify title to focus on core pyvenv.cfg home behavior

862142a

fix typo; remove host-relocatable mention; remove non-germane copying…

1c8fb2d

…-venv section

fix typos, grammar

c542890

ncoghlan approved these changes Jul 2, 2025

View reviewed changes

rickeylev and others added 3 commits July 2, 2025 10:37

Apply suggestions from code review

3240227

Co-authored-by: Alyssa Coghlan <[email protected]>

fix up markdown and text width

557cb71

fix title underlines

0579623

hugovk changed the title ~~PEP xxx: relative virtual environments, initial draft~~ PEP 796: relative virtual environments, initial draft Jul 2, 2025

rickeylev marked this pull request as ready for review July 2, 2025 17:54

rickeylev requested a review from a team as a code owner July 2, 2025 17:54

link to relative venv reference implementation

c9388b3

rickeylev mentioned this pull request Jul 2, 2025

gh-135773: have pyvenv.cfg without home key anchor a venv and deduce home python/cpython#135831

Merged

ncoghlan reviewed Jul 4, 2025

View reviewed changes

peps/pep-0796.rst Outdated Show resolved Hide resolved

Apply suggestions from code review

b959f24

Co-authored-by: Alyssa Coghlan <[email protected]>

zanieb reviewed Jul 6, 2025

View reviewed changes

hugovk reviewed Jul 11, 2025

View reviewed changes

	compatible platforms. Portable venvs are appealing because virtual environments
	compatible platforms. Portable virtual environments are appealing because virtual environments

	that, it allows tools like ``bazel`` or ``venvstacks`` to more easily prepare
	that, it allows tools like Bazel or venvstacks to more easily prepare

		Tools that work around the absolute ``home`` key limitation the way ``bazel``
		and ``venvstacks`` currently do (omitting the ``home`` key, or editing it after

	`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__
	`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.

	* `python-build-standalone <https://github.com/astral-sh/python-build-standalone>`__:
	* `python-build-standalone <https://github.com/astral-sh/python-build-standalone>`__

	* `GH-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__
	* `gh-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__

Uh oh!

PEP 796: relative virtual environments, initial draft #4476

Are you sure you want to change the base?

PEP 796: relative virtual environments, initial draft #4476

Conversation

rickeylev commented Jun 30, 2025 • edited by ncoghlan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Basic requirements (all PEP Types)

Standards Track requirements

Uh oh!

Uh oh!

hugovk commented Jun 30, 2025

Uh oh!

rickeylev commented Jun 30, 2025

Uh oh!

hugovk commented Jun 30, 2025

Uh oh!

rickeylev commented Jul 2, 2025

Uh oh!

ncoghlan commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ncoghlan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk commented Jul 2, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rickeylev commented Jun 30, 2025 •

edited by ncoghlan

Loading

ncoghlan commented Jul 2, 2025 •

edited

Loading