PEP 796: Relative Virtual Environments [initial draft]

[rickeylev]

Basic requirements (all PEP Types)

• Read and followed PEP 1 & PEP 12
• File created from the latest PEP template
• PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header
• Title clearly, accurately and concisely describes the content in 79 characters or less
• Core dev/PEP editor listed as Author or Sponsor, and formally confirmed their approval
• Author, Status (Draft), Type and Created headers filled out correctly
• PEP-Delegate, Topic, Requires and Replaces headers completed if appropriate
• Required sections included
  • Abstract (first section)
  • Copyright (last section; exact wording from template required)
• Code is well-formatted (PEP 7/PEP 8) and is in code blocks, with the right lexer names if non-Python
• PEP builds with no warnings, pre-commit checks pass and content displays as intended in the rendered HTML
• Authors/sponsor added to .github/CODEOWNERS for the PEP

Standards Track requirements

• PEP topic discussed in a suitable venue with general agreement that a PEP is appropriate
• Suggested sections included (unless not applicable)
  • Motivation
  • Rationale
  • Specification
  • Backwards Compatibility
  • Security Implications
  • How to Teach This
  • Reference Implementation
  • Rejected Ideas
  • Open Issues
• Python-Version set to valid (pre-beta) future Python version, if relevant
• Any project stated in the PEP as supporting/endorsing/benefiting from the PEP formally confirmed such
• Right before or after initial merging, PEP discussion thread created and linked to in Discussions-To and Post-History

Work towards python/cpython#136051

---

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

[hugovk]

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:

• https://peps.python.org/pep-0001/#start-with-an-idea-for-python
• https://peps.python.org/pep-0001/#submitting-a-pep

[rickeylev]

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]

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!

[hugovk]

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.

[AA-Turner]

@paveldikov thank you for the comment, please could you re-post it on Discourse? The peps repo / PR discussion is mainly for editorial discussion, rather than substantive comment on the proposal itself.

A

[rickeylev]

Thanks for the reviews! I'm out from under $dayJob and vacation backlogs a bit now and addressed comments.

[StanFromIreland]

Some little notes

[ncoghlan]

Belatedly removed the DO-NOT-MERGE label (that was added pending the Discourse discussion and sponsorship of the PEP)

[AA-Turner]

The PEP is currently missing a Security Implications section, which I think should be added given that arbitrary directory traversal is permitted -- at the very least explaining why this is fine.

Several editorial notes, I think the Motivation & Rationale sections should be strengthened to focus on the benefits from relative environments, there is currently (I believe) a lot of assumed context.

The PEP also discusses at some length a broader proposal for reloacatable venvs. Is it worth considering making that the proposal here? I don't know the specifics, so it might be that the changes needed for 'relocatable' are too large to tackle in one go.

A

[AA-Turner]

This sentence doesn't add much. It's also somewhat confused by the next para which says that the reason they are wanted is because they're prohibited.

I would first (briefly) explain to the reader what the home field in pyvenv.cfg is for, then go on to discuss the benefits of relative paths. Assume the reader is technically competent, but doesn't have all the context you do of the history here.

[ncoghlan]

Suggested change

	There are two main motivations for allowing relative paths in ``pyvenv.cfg``.
	The ``home`` field in ``pyvenv.cfg`` is used on interpreter startup to determine the actual Python
	interpreter installation that is used to execute code in that virtual environment. Currently,
	this path is required to be absolute for correct virtual environment operation - as the original PEP
	adding virtual environments didn't cover any specific way of processing relative paths, their
	behaviour is implementation dependent. CPython releases up to and including CPython 3.14
	resolve them relative to the current process working directory, making them too unreliable to
	use in practice.

@AA-Turner has a point that the subsection could benefit from restructuring in general, though:

• move the rationale paragraphs up here to the motivation section
• move some of the technical details motivation text down to the rationale section
• add the rationale for excluding the tool dependent environment portability features (those problems can be solved at the tool level, and need to be solved at the tool level because the right answers are dependent on the exact intended usage model of the relative virtual environments)

For PEP readers that aren't already familiar with the problem, the core points we want to get across are that there are use cases that rely on relative virtual environments (motivation), and while we can deal with most of the challenges involved in setting them up in ways we're happy with, the ways we have to deal with this problem are particularly horrible, and we'd like to ditch them in favour of properly defined interpreter level handling of relative paths in the home key (rationale).

[rickeylev]

Rewrote large portions of motivation/rationale. PTAL

[rickeylev]

Applied suggestions and addressed a few comments; didn't have time to address everything, though.

[rickeylev]

Ok, all pending comments addressed (I think. The Github UI frequently tricks me 😂 )

PTAL

re: security section: added. At least, insofar as I understand your concern correctly.

re: motivation and rationale strengthening: Thanks! Yeah, honestly, a big issue I've had writing this that "Motivation" and "Rationale" are, to me at least, practically synonyms. I did my best to better separate "Why do this change at all?" (motivation) and "Implementation decision and why that decision" (rationale).

re: proposing relocatable venv in this pep: I added a section about why this pep limits its scope to just the core interpreter.

[rickeylev]

Rewrote large portions of motivation/rationale. PTAL

[rickeylev]

This is now more directly answered in paragraph 2 of the motivation. I didn't want the start of the motivation to distractingly delve early into details of "why a portable venv" matters, so those details are in a "why portable virtual environments matter" subsection of motivation.