Description

ned-deily

opened on Mar 2, 2022

Issue body actions

BPO	46901
Nosy	@ronaldoussoren, @ned-deily, @zooba

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2022-03-02.17:45:33.785>
labels = ['OS-mac', '3.11', 'docs']
title = 'Deprecate and eventually remove macOS-only PYTHONEXECUTABLE environ variable'
updated_at = <Date 2022-03-02.17:45:33.785>
user = 'https://github.com/ned-deily'

bugs.python.org fields:

activity = <Date 2022-03-02.17:45:33.785>
actor = 'ned.deily'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'macOS']
creation = <Date 2022-03-02.17:45:33.785>
creator = 'ned.deily'
dependencies = []
files = []
hgrepos = []
issue_num = 46901
keywords = []
message_count = 1.0
messages = ['414382']
nosy_count = 4.0
nosy_names = ['ronaldoussoren', 'ned.deily', 'docs@python', 'steve.dower']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue46901'
versions = ['Python 3.11']

Activity

1. ned-deily commented on Mar 2, 2022

   

   ned-deily

   on Mar 2, 2022

   MemberAuthor

   More actions

   The PYTHONEXECUTABLE is a holdover from old Python 2 days; AFAIK, it was specifically to support the Build Applet tool which could be used to build macOS app bundles in Python 2. The only place in current Py3 releases where it is used is in the standard library is in the launch of IDLE.app, a usage that should be able to be eliminated. Otherwise, there shouldn't be any need for it by third-parties. For 3.11, we could eliminate its use by IDLE.app and add a deprecation warning to the docs; not sure about an execution time warning?

   https://docs.python.org/3/using/cmdline.html#envvar-PYTHONEXECUTABLE
2. ned-deily

   added

   3.11only security fixesonly security fixes

   on Mar 2, 2022
3. ned-deily

   assigned

   docspython

   on Mar 2, 2022
4. ned-deily

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   OS-mac

   on Mar 2, 2022
5. ezio-melotti

   transferred this issue fromon Apr 10, 2022
6. rickeylev commented on May 6, 2025

   

   rickeylev

   on May 6, 2025

   Contributor

   More actions

   Hi,

   I've found the PYTHONEXECUTABLE environment variable incredibly valuable for the particular case of relocatable virtual environments in read-only file systems using a wrapper script (not symlink) for the venv's bin/python. This case is common in the Bazel ecosystem, where as much as possible is created and determined at build time, and then copied over to a target system to actually run as-is.

   In this case, what the PYTHONEXECUTABLE envvar essentially allows is allowing Python to find the underlying interpreter's home directory (which lets it find the interpreter's stdlib etc), while letting site.py's logic look at the venv's directory for e.g site-packages and sys.executable.

   The net effect is you can copy a venv directory between systems without having to recreate pyvenv.cfg or the symlinks.

   Also: PYTHONEEXECUTABLE is no-longer Mac specific. I'd have to go dig up issue/PR, but checking it only on Mac was intentionally dropped.
7. ned-deily

   closed this as not plannedon May 18, 2026
8. ned-deily

   reopened this on May 18, 2026
9. ned-deily commented on May 18, 2026

   

   ned-deily

   on May 18, 2026

   MemberAuthor

   More actions

   Looking into this a bit more, I would like to see the use case of relocatable virtual environments treated as a separate feature that is properly supported and documented rather than using a backdoor 'trick'. I could be misremembering but I think the fact that PYTHONEXECUTABLE is no longer macOS-specific is likely due to an oversight during the rewrite of getpath processing in Python 3.11 rather than an intended change. Most of the references to PYTHONEXECUTABLE in the cpython repo are still macOS-specific. And venvs are specifically documented as being not portable in the general case. I expect there are already other open issues requesting venv portability.
10. ned-deily

    marked PYTHONEXECUTABLE envvar incorrectly doc'd as mac-only and ignored by -E/-I #133525 as a duplicate of this issue on May 18, 2026
11. mjpieters commented on Jun 5, 2026

    

    mjpieters

    on Jun 5, 2026

    Contributor

    More actions

    I could be misremembering but I think the fact that PYTHONEXECUTABLE is no longer macOS-specific is likely due to an oversight during the rewrite of getpath processing in Python 3.11 rather than an intended change.

    PYTHONEXECUTABLE is indeed no longer Mac specific, it is mostly a synonym for __PYVENV_LAUNCHER__ now; see getpath.py:

    cpython/Modules/getpath.py

    Lines 304 to 325 in 2f064fb

    	if ENV_PYTHONEXECUTABLE or ENV___PYVENV_LAUNCHER__:
    	# If set, these variables imply that we should be using them as
    	# sys.executable and when searching for venvs. However, we should
    	# use the argv0 path for prefix calculation
    	if os_name == 'darwin' and WITH_NEXT_FRAMEWORK:
    	# In a framework build the binary in {sys.exec_prefix}/bin is
    	# a stub executable that execs the real interpreter in an
    	# embedded app bundle. That bundle is an implementation detail
    	# and should not affect base_executable.
    	base_executable = f"{dirname(library)}/bin/python{VERSION_MAJOR}.{VERSION_MINOR}"
    	else:
    	# Use the real executable as our base, or argv[0] otherwise
    	# (on Windows, argv[0] is likely to be ENV___PYVENV_LAUNCHER__; on
    	# other platforms, real_executable is likely to be empty)
    	base_executable = real_executable or executable
    	if not real_executable:
    	real_executable = base_executable
    	#real_executable_dir = dirname(real_executable)
    	executable = ENV_PYTHONEXECUTABLE or ENV___PYVENV_LAUNCHER__
    	executable_dir = dirname(executable)

    This is the only location where either variable is actually read and used, outside of tests.

Issue actions