Repository navigation
PEP 829: KeyError: "local variable ''sitedir'' is not defined" #149671
Copy link
Copy link
Closed
Labels
3.15bugs and security fixesbugs and security fixesstdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directorytype-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error
Description
Bug report
Bug description:
Re-posting from sphinx-doc/sphinx#14426 (comment).
Reproducible with CPython docs:
Details
❯ make -C Doc clean venv html PYTHON=3.15
rm -rf ./venv
rm -rf build/*
Creating venv in ./venv
Using CPython 3.15.0b1 interpreter at: /Library/Frameworks/Python.framework/Versions/3.15/bin/python3.15
Creating virtual environment at: ./venv
Activate with: source venv/bin/activate
warning: The `--pylock` option is experimental and may change without warning. Pass `--preview-features pylock` to disable this warning.
Using Python 3.15.0b1 environment at: venv
Prepared 28 packages in 6ms
Installed 28 packages in 91ms
+ alabaster==1.0.0
+ babel==2.18.0
+ blurb==2.0.0
+ certifi==2026.4.22
+ charset-normalizer==3.4.7
+ docutils==0.21.2
+ idna==3.13
+ imagesize==1.5.0
+ jinja2==3.1.6
+ linklint==1.0.0
+ markupsafe==2.1.5
+ packaging==24.2
+ pygments==2.20.0
+ python-docs-theme==2026.4
+ requests==2.33.1
+ roman-numerals==4.1.0
+ roman-numerals-py==4.1.0
+ snowballstemmer==2.2.0
+ sphinx==8.2.3
+ sphinx-notfound-page==1.0.4
+ sphinxcontrib-applehelp==2.0.0
+ sphinxcontrib-devhelp==2.0.0
+ sphinxcontrib-htmlhelp==2.1.0
+ sphinxcontrib-jsmath==1.0.1
+ sphinxcontrib-qthelp==2.0.0
+ sphinxcontrib-serializinghtml==2.0.0
+ sphinxext-opengraph==0.13.0
+ urllib3==2.6.3
The venv has been created in the ./venv directory
mkdir -p build
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
KeyError: "local variable ''sitedir'' is not defined"
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
KeyError: "local variable ''sitedir'' is not defined"
blurb version 2.0.0
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
KeyError: "local variable ''sitedir'' is not defined"
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
KeyError: "local variable ''sitedir'' is not defined"
sphinx-build 8.2.3
Building NEWS from Misc/NEWS.d with blurb
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
KeyError: "local variable ''sitedir'' is not defined"
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
KeyError: "local variable ''sitedir'' is not defined"
PATH=./venv/bin:$PATH sphinx-build --builder html --doctree-dir build/doctrees --jobs auto --fail-on-warning . build/html
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
KeyError: "local variable ''sitedir'' is not defined"
Error in import line from /Users/hugo/github/python/cpython/main/Doc/venv/lib/python3.15/site-packages/sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('sphinxcontrib',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('sphinxcontrib', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('sphinxcontrib', [os.path.dirname(p)])));m = m or sys.modules.setdefault('sphinxcontrib', types.ModuleType('sphinxcontrib'));mp = (m or []) and m.__dict__.setdefault('__path__',[]);(p not in mp) and mp.append(p)
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
KeyError: "local variable ''sitedir'' is not defined"
Running Sphinx v8.2.3
loading translations [en]... done
matplotlib is not installed, social cards will not be generated
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 548 source files that are out of date
updating environment: [new config] 548 added, 0 changed, 0 removed
reading sources... [100%] whatsnew/changelog .. whatsnew/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/hugo/github/python/cpython/main/Doc/howto/argparse.rst: document is referenced in multiple toctrees: ['howto/index', 'library/argparse'], selecting: library/argparse <- howto/argparse
done
preparing documents... done
copying assets...
copying downloadable files... [100%] includes/tzinfo_examples.py
copying static files...
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/basic.css
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/language_data.js
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/documentation_options.js
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/classic.css
Writing evaluated template result to /Users/hugo/github/python/cpython/main/Doc/build/html/_static/sidebar.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] whatsnew/3.5 .. whatsnew/index
generating indices... genindex py-modindex done
writing additional pages... download index search opensearch done
copying images... [100%] using/win_install_freethreaded.png
dumping search index in English (code: en)... done
dumping object inventory... done
Writing glossary.json
profiling_trace: Injected 38 trace events into profiling-sampling-visualization.js
Linklint: unlinked 3584 refs: 2000 duplicate, 1584 self
build succeeded.
The HTML pages are in build/html.
Build finished. The HTML pages are in build/html.Minimal repro:
❯ echo "import sys; sys._getframe(1).f_locals['sitedir']" > legacy.pth
❯ python3.14 -c "import site; site.addsitedir('.')"
❯ python3.15 -c "import site; site.addsitedir('.')"
Found existing alias for "python3.15". You should use: "p5"
Error in import line from /Users/hugo/github/python/cpython/main/legacy.pth: import sys; sys._getframe(1).f_locals['sitedir']
Traceback (most recent call last):
File "<frozen site>", line 319, in _exec_imports
File "<string>", line 1, in <module>
import site; site.addsitedir('.')
~~~~~~~~~~~~~~~~^^^^^
KeyError: "local variable ''sitedir'' is not defined"Not reproducible in a8, but is in b1.
Bisects to PEP 829: #149109, cc @warsaw.
CPython versions tested on:
3.15
Operating systems tested on:
macOS
Linked PRs
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
3.15bugs and security fixesbugs and security fixesstdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directorytype-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error
Activity
warsaw commentedon May 11, 2026
Given that this is poking into internal undocumented implementation details, I don't consider this a breaking change. Once the fix for #149504 lands, you can use
sys._getframe(3), but even that is subject to change, so I wouldn't rely on it. Also, if someone callsaddsitedir(..., defer_processing_start_files=True)you might not get the sitedir you think you're getting.I'd like to understand the use case in more detail so that we can possibly design an API we can make guarantees about. For example, one of the things I've thought about is calling entry points with arguments (currently they're called with no arguments).
That said, I'm tempted to close this as won't fix for 3.15 and we can work out a more principled fix for 3.16.
🧪 test(conftest): strip broken nspkg.pth files under py3.15 (#3937)
hugovk commentedon May 12, 2026
Use case for the Python docs:
The error doesn't stop the build and we still get the same HTML output with 3.14 and 3.15. (I din't check other builders like EPUB.)
It's coming from the sphinxcontrib-jsmath extension, which hasn't had any releases since 2019 (https://pypi.org/project/sphinxcontrib-jsmath/#history) and its wheel contains a
sphinxcontrib_jsmath-1.0.1-py3.7-nspkg.pthfile containingos.path.join(sys._getframe(1).f_locals['sitedir']:It's one of Sphinx's dependencies so will have high visibility:
A modern wheel built from https://github.com/sphinx-doc/sphinxcontrib-jsmath no longer has this file.
@AA-Turner please can you make a new release of sphinxcontrib-jsmath to remove these "errors"?
I expect there's other old wheels out there with similar legacy
.pthfiles, but I don't if they will cause real errors.hugovk commentedon May 14, 2026
Similar report at #149845.
python3.15 -m venv venv315crashes with a KeyError #149845 as a duplicate of this issuesuutari commentedon May 16, 2026
It seems to be quite common pattern to get access to the
sitedirvariable via thef_localsofframe(1)in .pth files. I found two other libs doing that when trying to run Python 3.15 on my system, which has some libs installed to dist-packages from Ubuntu 24.04 debs. Namely matplotlib and virtualenvwrapper:hugovk commentedon May 18, 2026
Looking at the top 5k PyPI packages, these 17 contain
-nspkg.pthwithf_locals+sitedir:snowflake-snowpark-pythonsphinxcontrib-jsmathgoogle-generativeaiamazon-ionfunctions-frameworktesting-postgresqltesting-common-databasepastedeployautogluon-coreautogluon-featuresintuit-oauthautogluonautogluon-tabularautogluon-commonpasteautogluon-timeseriesautogluon-multimodalMost of those are recent releases and all contain
namespace_packages=insetup.py,setup.cfgor similar.The setuptools docs say it's "now considered deprecated despite the fact they still linger in many existing packages", and it likely lingers because setuptools raises no deprecation warnings.
warsaw commentedon May 18, 2026
It's a hack for a deprecated and unnecessary feature. I really really do not want to fix this in CPython, especially if...
... this doesn't actually affect functionality, which it shouldn't if they are using proper PEP 420 namespace packages anyway. If it's just that you get an annoying traceback, maybe we can just suppress any exceptions in
.pthfiles unless-vis given? The other (bad) idea is to special case*-nspkg.pthfiles but I also really don't want to do that either.hugovk commentedon May 18, 2026
Yeah, the only reports we've had so far are annoying tracebacks and not real errors.
If we close as won't fix, this is a good nudge for projects to fix their deprecated code, which we can see has begun from the PRs linking here.
Do you think it would be worth catching this
KeyErrorand raising a more actionable message?warsaw commentedon May 18, 2026
Cool. Demoting the exception to
--verboseis pretty easy change.I think I'd rather not because
KeyErrorcould be raised by code not doing this hack and I don't want to specialize the logic too much. I think I'll do the traceback demotion for now and maybe add a landmine to promote it to always printing the exception in 3.16. Then close this bug as Won't Fix and hope projects will fix their deprecated code.warsaw commentedon May 18, 2026
Okay, final decision! I talked to @pradyunsg and @jaraco at the PyCon sprint. They are going to remove the
-nspkg.pthbehavior in setuptools, and we are not going to make any changes to CPython. Won't Fix.17 remaining items
vstinner commentedon Jun 12, 2026
@pradyunsg and @jaraco: Did you create an issue or a pull request for that in setuptools?
00488: pythongh-149671: Restore compatibility with setuptools nspkg.p…
hroncok commentedon Jun 13, 2026
We are receiving more and more Fedora bug reports from the affected projects. Most recently https://bugzilla.redhat.com/show_bug.cgi?id=2487621
I am mostly posting this here to demonstrate that the "harmless" traceback is, in fact, not so harmless. We are backporting #151319
vstinner commentedon Jun 15, 2026
Example of impacted projects:
ipahealthcheck-0.19-py3.15-nspkg.pthgoogle_cloud_core-2.3.3-py3.15-nspkg.pthPaste-3.10.1-py3.15-nspkg.pthgh-149671: Restore compatibility with setuptools -nspkg.pth files in …
[3.15] gh-149671: Restore compatibility with setuptools -nspkg.pth fi…
vstinner commentedon Jun 15, 2026
I merged my changes which restores compatibility with Python 3.14: add again "sitedir" variable.
I can no longer reproduce the issue using #149671 (comment) reproducer. So I close this issue.
hugovk commentedon Jun 15, 2026
Also can't reproduce via
make -C Doc clean venv html PYTHON=../python.exewith latestmain.Thanks all!
vstinner commentedon Jun 15, 2026
PEP 829 versus real life 🤣
pythongh-149671: Restore compatibility with setuptools -nspkg.pth fil…
pythongh-156404: Restore the 'fullname' variable for .pth import lines
pythongh-156404: Restore the 'fullname' variable for .pth import lines
gh-156404: Restore the 'fullname' variable for .pth import lines (#15…
pythongh-156404: Restore the 'fullname' variable for .pth import lines (