Skip to content

PEP 829: KeyError: "local variable ''sitedir'' is not defined" #149671

Description

@hugovk

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

Activity

  1. added
    type-bugAn unexpected behavior, bug, or error
    3.15bugs and security fixes
    stdlibStandard Library Python modules in the Lib/ directory
    on May 11, 2026
  2. warsaw commented on May 11, 2026

    @warsaw
    Member

    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 calls addsitedir(..., 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.

  3. self-assigned this
    on May 11, 2026
  4. hugovk commented on May 12, 2026

    @hugovk
    MemberAuthor

    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.pth file containing os.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 .pth files, but I don't if they will cause real errors.

  5. hugovk commented on May 14, 2026

    @hugovk
    MemberAuthor

    Similar report at #149845.

  6. suutari commented on May 16, 2026

    @suutari

    It seems to be quite common pattern to get access to the sitedir variable via the f_locals of frame(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.
    >>>
  7. hugovk commented on May 18, 2026

    @hugovk
    MemberAuthor

    Looking at the top 5k PyPI packages, these 17 contain -nspkg.pth with f_locals + sitedir:

    Package Version Released Downloads/month
    snowflake-snowpark-python 1.50.1 2026-05-06 45,618,920
    sphinxcontrib-jsmath 1.0.1 2019-01-21 25,131,142
    google-generativeai 0.8.6 2025-12-16 16,631,612
    amazon-ion 0.13.0 2025-01-10 15,648,010
    functions-framework 3.10.1 2026-02-17 9,240,267
    testing-postgresql 1.3.0 2016-02-04 3,716,859
    testing-common-database 2.0.3 2017-10-23 3,645,811
    pastedeploy 3.1.0 2023-11-21 2,971,729
    autogluon-core 1.5.0 2025-12-19 1,275,539
    autogluon-features 1.5.0 2025-12-19 1,226,697
    intuit-oauth 1.2.6 2024-08-01 1,174,523
    autogluon 1.5.0 2025-12-19 1,154,727
    autogluon-tabular 1.5.0 2025-12-19 1,147,373
    autogluon-common 1.5.0 2025-12-19 1,123,796
    paste 3.10.1 2024-05-01 1,075,671
    autogluon-timeseries 1.5.0 2025-12-19 1,013,556
    autogluon-multimodal 1.5.0 2025-12-19 959,508
    Total (17 packages) 132,755,740

    Most of those are recent releases and all contain namespace_packages= in setup.py, setup.cfg or 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.

  8. warsaw commented on May 18, 2026

    @warsaw
    Member

    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 .pth files unless -v is given? The other (bad) idea is to special case *-nspkg.pth files but I also really don't want to do that either.

  9. hugovk commented on May 18, 2026

    @hugovk
    MemberAuthor

    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 KeyError and raising a more actionable message?

  10. warsaw commented on May 18, 2026

    @warsaw
    Member

    Yeah, the only reports we've had so far are annoying tracebacks and not real errors.

    Cool. Demoting the exception to --verbose is pretty easy change.

    Do you think it would be worth catching this KeyError and raising a more actionable message?

    I think I'd rather not because KeyError could 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.

  11. warsaw commented on May 18, 2026

    @warsaw
    Member

    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. Won't Fix.

  12. 17 remaining items

  13. vstinner commented on Jun 12, 2026

    @vstinner
    Member

    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?

  14. added a commit that references this issue on Jun 13, 2026
  15. hroncok commented on Jun 13, 2026

    @hroncok
    Contributor

    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

  16. vstinner commented on Jun 15, 2026

    @vstinner
    Member

    We 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:

  17. added 2 commits that reference this issue on Jun 15, 2026
  18. vstinner commented on Jun 15, 2026

    @vstinner
    Member

    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.

  19. hugovk commented on Jun 15, 2026

    @hugovk
    MemberAuthor

    Also can't reproduce via make -C Doc clean venv html PYTHON=../python.exe with latest main.

    Thanks all!

  20. vstinner commented on Jun 15, 2026

    @vstinner
    Member

    PEP 829 versus real life 🤣

    Image
  21. added a commit that references this issue on Jun 17, 2026
  22. added 2 commits that reference this issue on Aug 26, 2026
  23. added a commit that references this issue on Aug 26, 2026
  24. added a commit that references this issue on Aug 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

3.15bugs and security fixesstdlibStandard Library Python modules in the Lib/ directorytype-bugAn unexpected behavior, bug, or error

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions