Repository navigation
Show a better error message when PYTHONHOME is wrong #125873
Description
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
Activity
ZeroIntensity commentedon Oct 23, 2024
I think the most reasonable fix would be to change this line to something like:
PR welcome!
pythongh-125873: Add hint when failing to import encodings
pythongh-125873: Add hint when failing to import encodings
skirpichev commentedon Oct 27, 2024
You can also damage
PYTHONPLATLIBDIR, maybe more environment variables, e.g.:ZeroIntensity commentedon Oct 27, 2024
You could, but what makes
PYTHONHOMEspecial is that it's "required" to do anything with the interpreter--explicitly messing with other variables is the user's fault IMO.pythongh-125873: Improve error message when `PYTHONHOME` is invalid
pythongh-125873: Improve error message when `PYTHONHOME` is invalid
FFY00 commentedon Dec 4, 2024
Tangentially related: we should also fail earlier if
PYTHONHOME,PYTHONPLATLIBDIR, etc. are not directories in the fist place.FFY00 commentedon Dec 4, 2024
Related to GH-125873, where this failure mode is triggered by specifying a bad
homeinpyvenv.cfg. A custom error message should be used for that case, though.pythonGH-125873: error out in getpath when unable to find stdlib
pythonGH-125873: error out in getpath when unable to find stdlib
gh-125873: Improve error message when PYTHONHOME is invalid (#126027)