Show a better error message when PYTHONHOME is wrong

Feature or enhancement

Proposal:

Currently, when PYTHONHOME is wrong, python says ModuleNotFoundError: No module named 'encodings'. This is error makes it sound like a module is missing, when it's actually a part of the core interpreter configuration that is broken, which the error doesn't tell.

Ideally, the error would show if a pyvenv.cfg was loaded, as a wrong home path causes this error.

Example pyenv Python 3.12 on Ubuntu 24.04:

$ PYTHONHOME=/dev/null python
Python path configuration:
  PYTHONHOME = '/dev/null'
  PYTHONPATH = (not set)
  program name = 'python'
  isolated = 0
  environment = 1
  user site = 1
  safe_path = 0
  import site = 1
  is in build tree = 0
  stdlib dir = '/dev/null/lib/python3.12'
  sys._base_executable = '/home/konsti/.local/bin/python'
  sys.base_prefix = '/dev/null'
  sys.base_exec_prefix = '/dev/null'
  sys.platlibdir = 'lib'
  sys.executable = '/home/konsti/.local/bin/python'
  sys.prefix = '/dev/null'
  sys.exec_prefix = '/dev/null'
  sys.path = [
    '/dev/null/lib/python312.zip',
    '/dev/null/lib/python3.12',
    '/dev/null/lib/python3.12/lib-dynload',
  ]
Fatal Python error: init_fs_encoding: failed to get the Python codec of the filesystem encoding
Python runtime state: core initialized
ModuleNotFoundError: No module named 'encodings'

Current thread 0x00007a7eee702b80 (most recent call first):
  <no Python frame>

Example python-build-standalone on Ubuntu 24.04:

$ PYTHONHOME=/dev/null python3.13
Fatal Python error: Failed to import encodings module
Python runtime state: core initialized
ModuleNotFoundError: No module named 'encodings'

Current thread 0x000072ef39049b80 (most recent call first):
  <no Python frame>

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

There are several bug reports featuring this error: https://github.com/python/cpython/issues?q=is%3Aissue+%22ModuleNotFoundError%3A+No+module+named+%27encodings%27%22+

https://stackoverflow.com/questions/38132755/importerror-no-module-named-encodings

The error is occurring for users in various communities: https://www.google.com/search?q=%22ModuleNotFoundError%3A+No+module+named+%27encodings%27%22

Linked PRs

• gh-126027
• gh-127616

まず、issue で説明されている PYTHONHOME と pyvenv.cfg の処理を確認し、続いて現在の方向性について、リンクされている PR gh-126027 と gh-127616 を調査します。/dev/null の例を再現して起動時の診断を比較します。完了の条件は、encodings が見つからないと報告するだけでなく、不正な core 設定を明確に特定することです。