Repository navigation
PEP 829: KeyError: "local variable ''sitedir'' is not defined" #149671
Description
Activity
- addedtype-bugAn unexpected behavior, bug, or errorAn unexpected behavior, bug, or error3.15bugs and security fixesbugs and security fixesstdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directory
on 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.
- added a commit that references this issue
on 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.Reacted by Maciej OlkoSimilar report at #149845.
- marked
python3.15 -m venv venv315crashes with a KeyError #149845 as a duplicate of this issueon May 14, 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:$ python3.15 Error in import line from /usr/lib/python3/dist-packages/matplotlib-3.6.3-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('mpl_toolkits',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('mpl_toolkits', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('mpl_toolkits', [os.path.dirname(p)])));m = m or sys.modules.setdefault('mpl_toolkits', types.ModuleType('mpl_toolkits'));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 325, in _exec_imports File "<string>", line 1, in <module> KeyError: "local variable ''sitedir'' is not defined" Error in import line from /usr/lib/python3/dist-packages/virtualenvwrapper-4.8.4-nspkg.pth: import sys, types, os;has_mfs = sys.version_info > (3, 5);p = os.path.join(sys._getframe(1).f_locals['sitedir'], *('virtualenvwrapper',));importlib = has_mfs and __import__('importlib.util');has_mfs and __import__('importlib.machinery');m = has_mfs and sys.modules.setdefault('virtualenvwrapper', importlib.util.module_from_spec(importlib.machinery.PathFinder.find_spec('virtualenvwrapper', [os.path.dirname(p)])));m = m or sys.modules.setdefault('virtualenvwrapper', types.ModuleType('virtualenvwrapper'));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 325, in _exec_imports File "<string>", line 1, in <module> KeyError: "local variable ''sitedir'' is not defined" Python 3.15.0b1 (main, May 8 2026, 10:07:35) [GCC 13.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>>
Looking at the top 5k PyPI packages, these 17 contain
-nspkg.pthwithf_locals+sitedir:Package Version Released Downloads/month snowflake-snowpark-python1.50.1 2026-05-06 45,618,920 sphinxcontrib-jsmath1.0.1 2019-01-21 25,131,142 google-generativeai0.8.6 2025-12-16 16,631,612 amazon-ion0.13.0 2025-01-10 15,648,010 functions-framework3.10.1 2026-02-17 9,240,267 testing-postgresql1.3.0 2016-02-04 3,716,859 testing-common-database2.0.3 2017-10-23 3,645,811 pastedeploy3.1.0 2023-11-21 2,971,729 autogluon-core1.5.0 2025-12-19 1,275,539 autogluon-features1.5.0 2025-12-19 1,226,697 intuit-oauth1.2.6 2024-08-01 1,174,523 autogluon1.5.0 2025-12-19 1,154,727 autogluon-tabular1.5.0 2025-12-19 1,147,373 autogluon-common1.5.0 2025-12-19 1,123,796 paste3.10.1 2024-05-01 1,075,671 autogluon-timeseries1.5.0 2025-12-19 1,013,556 autogluon-multimodal1.5.0 2025-12-19 959,508 Total (17 packages) 132,755,740 Most 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.
It's a hack for a deprecated and unnecessary feature. I really really do not want to fix this in CPython, especially if...
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.)
... 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.Reacted by Hugo van KemenadeYeah, 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?Yeah, the only reports we've had so far are annoying tracebacks and not real errors.
Cool. Demoting the exception to
--verboseis pretty easy change.Do you think it would be worth catching this
KeyErrorand raising a more actionable message?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.Reacted by Hugo van KemenadeOkay, 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.Reacted by Hugo van Kemenade17 remaining items
Okay, final decision! I talked to @pradyunsg and @jaraco at the PyCon sprint. They are going to remove the -nspkg.pth behavior in setuptools, and we are not going to make any changes to CPython.
@pradyunsg and @jaraco: Did you create an issue or a pull request for that in setuptools?
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
Reacted by Barry WarsawWe are receiving more and more Fedora bug reports from the affected projects. Most recently https://bugzilla.redhat.com/show_bug.cgi?id=2487621
Example of impacted projects:
- FreeIPA:
ipahealthcheck-0.19-py3.15-nspkg.pth - python3-google-cloud-storage:
google_cloud_core-2.3.3-py3.15-nspkg.pth - fedora-third-party:
Paste-3.10.1-py3.15-nspkg.pth
- FreeIPA:
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.
Reacted by Hugo van KemenadeAlso can't reproduce via
make -C Doc clean venv html PYTHON=../python.exewith latestmain.Thanks all!
Reacted by Victor StinnerPEP 829 versus real life 🤣

- added a commit that references this issue
on Aug 26, 2026
Bug report
Bug description:
Re-posting from sphinx-doc/sphinx#14426 (comment).
Reproducible with CPython docs:
Details
Minimal repro:
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