FIX: pyplot auto-backend detection case-sensitivity fixup #29721

jayaddison · 2025-03-09T13:10:19Z

PR summary

There seems to be a case-sensitivity bug in the matplotlib.pyplot module code that decides whether to configure backend autodetection, and I think that this is the cause of the bug reported in #29713.

The bug means that a current interactive environment value of TkAgg is not detected as one of the possible values from a set that includes the string tkagg -- and so an auto-backend is not configured, as it would have been previously in v3.8.3 of this library.

A minimal repro example is provided below, for use in a container environment with no graphical/GUI environment available:

>>> import matplotlib.pyplot
>>> matplotlib.pyplot.new_figure_manager()
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    matplotlib.pyplot.new_figure_manager()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/matplotlib/pyplot.py", line 551, in new_figure_manager
    _warn_if_gui_out_of_main_thread()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/matplotlib/pyplot.py", line 528, in _warn_if_gui_out_of_main_thread
    canvas_class = cast(type[FigureCanvasBase], _get_backend_mod().FigureCanvas)
                                                ~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3/dist-packages/matplotlib/pyplot.py", line 369, in _get_backend_mod
    switch_backend(rcParams._get("backend"))
    ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/matplotlib/pyplot.py", line 433, in switch_backend
    raise ImportError(
    ...<2 lines>...
            newbackend, required_framework, current_framework))
ImportError: Cannot load backend 'TkAgg' which requires the 'tk' interactive framework, as 'headless' is currently running

PR checklist

"closes #0000" is in the body of the PR description to link the related issue
new and changed code is tested
Plotting related features are demonstrated in an example N/A
New Features and API Changes are noted with a directive and release note N/A
~~Documentation complies with general and docstring guidelines~~ N/A

Closes #29713.

jayaddison · 2025-03-10T11:02:10Z

Thinking about how to add test coverage here: I think that modifying/extending the test_backend_fallback_headless and test_backend_fallback_headful test cases might be a reasonable way to demonstrate the problem and/or fix:

matplotlib/lib/matplotlib/tests/test_rcparams.py

Lines 523 to 563 in b37dbe9

    
           @pytest.mark.skipif(sys.platform != "linux", reason="Linux only") 
        
           def test_backend_fallback_headless(tmp_path): 
        
               env = {**os.environ, 
        
                      "DISPLAY": "", "WAYLAND_DISPLAY": "", 
        
                      "MPLBACKEND": "", "MPLCONFIGDIR": str(tmp_path)} 
        
               with pytest.raises(subprocess.CalledProcessError): 
        
                   subprocess_run_for_testing( 
        
                       [sys.executable, "-c", 
        
                        "import matplotlib;" 
        
                        "matplotlib.use('tkagg');" 
        
                        "import matplotlib.pyplot;" 
        
                        "matplotlib.pyplot.plot(42);" 
        
                        ], 
        
                       env=env, check=True, stderr=subprocess.DEVNULL) 
        
           @pytest.mark.skipif( 
        
               sys.platform == "linux" and not _c_internal_utils.xdisplay_is_valid(), 
        
               reason="headless") 
        
           def test_backend_fallback_headful(tmp_path): 
        
               if parse_version(pytest.__version__) >= parse_version('8.2.0'): 
        
                   pytest_kwargs = dict(exc_type=ImportError) 
        
               else: 
        
                   pytest_kwargs = {} 
        
               pytest.importorskip("tkinter", **pytest_kwargs) 
        
               env = {**os.environ, "MPLBACKEND": "", "MPLCONFIGDIR": str(tmp_path)} 
        
               backend = subprocess_run_for_testing( 
        
                   [sys.executable, "-c", 
        
                    "import matplotlib as mpl; " 
        
                    "sentinel = mpl.rcsetup._auto_backend_sentinel; " 
        
                    # Check that access on another instance does not resolve the sentinel. 
        
                    "assert mpl.RcParams({'backend': sentinel})['backend'] == sentinel; " 
        
                    "assert mpl.rcParams._get('backend') == sentinel; " 
        
                    "assert mpl.get_backend(auto_select=False) is None; " 
        
                    "import matplotlib.pyplot; " 
        
                    "print(matplotlib.get_backend())"], 
        
                   env=env, text=True, check=True, capture_output=True).stdout 
        
               # The actual backend will depend on what's installed, but at least tkagg is 
        
               # present. 
        
               assert backend.strip().lower() != "agg"

jayaddison · 2025-03-10T11:29:52Z

It's possible to re-order some of the import and get_backend code lines in test_backend_fallback_headful to get the test to fail without this fix and pass with it in place -- but I'm not completely certain what the expected logic should be, so I'll open this PR for review/feedback.

timhoffm

Note: I was wondering whether this is the right case to handle the case. Alternatives could be

validate_backend() coercing to lower-case. See

matplotlib/lib/matplotlib/rcsetup.py

Line 280 in b37dbe9

def validate_backend(s):

While we could do this, the BackendRegistry generally accepts arbitrary casing and coerces internally. Therefore, it may be slightly more consistent to keep the name as is in rcParams, so that the user always sees the name as given: They may use matplotlib.use("TkAgg") and set "TkAgg" in their matplotlibrc file. Then it's slightly awkward to return the lower-case variant for rcParams["backend_fallback"] - though one could still argue that eager normalization is still the way to go. I have no strong opinion here.
Push everything down to the BackendRegistry. While this would be nice in principle, we have a very specific request here: "Is the given backend name an available interactive backend, but not webagg or nbagg" and that's not easy to express as a high-level BackendRegistry API that could support arbitrary casing.

I therefore think the present solution is right.

jayaddison · 2025-03-10T18:56:23Z

@nileshpatra can you confirm that this fixup (f45707d) resolves the problems you encountered during unit tests for matplotlib-dependent packages? I think it should do, but it would be good to make sure.

ianthomas23 · 2025-03-11T11:46:36Z

Thanks @jayaddison, this is a bug that I introduced and the fix here looks good to me. I think you are looking in the right place for a test, but it might be a little awkward due to the subprocess approach.

jayaddison · 2025-03-11T12:37:07Z

Thank you @ianthomas23 @timhoffm for the code reviews. Also, I think I've figured out what could be some viable test coverage:

Given that test_backend_fallback_headless tests a negative/failure case (the ability to open a tkagg output when headless mode is active is expected to cause a failure), I think that test coverage for this change should add a second headless test that presents a successful rendering case. And to do that, it should be possible I think to import matplotlib.pyplot followed by creating a plot directly (no matplotlib.use / other imports required).

I've tested that theory in a shell with and without the fix in place and it seems to behave as expected; I'll try adding it to the test suite in a few moments.

lib/matplotlib/tests/test_rcparams.py

tacaswell · 2025-03-12T20:48:03Z

Can we squash this to one or two commits?

Co-authored-by: Ian Thomas <ianthomas23@gmail.com>

nileshpatra · 2025-03-13T17:55:04Z

Now that all comments are addressed, could this be merged?

On 13 March 2025 2:18:25 am IST, Thomas A Caswell ***@***.***> wrote: tacaswell left a comment (matplotlib/matplotlib#29721) Can we squash this to one or two commits? -- Reply to this email directly or view it on GitHub: #29721 (comment) You are receiving this because you were mentioned. Message ID: ***@***.***>

Best, Nilesh

ianthomas23

Thanks @jayaddison. CI failure is unrelated.

…-sensitivity fixup

jayaddison · 2025-03-14T09:31:35Z

Thank you @ianthomas23!

…721-on-v3.10.x Backport PR #29721 on branch v3.10.x (FIX: pyplot auto-backend detection case-sensitivity fixup)

FIX: pyplot auto-backend detection case-sensitivity fixup

f45707d

github-actions bot added the topic: pyplot API label Mar 9, 2025

jayaddison mentioned this pull request Mar 9, 2025

[Bug]: Matplotlib selects TkAgg backend on LXC containers #29713

Closed

jayaddison marked this pull request as ready for review March 10, 2025 11:29

timhoffm approved these changes Mar 10, 2025

View reviewed changes

github-actions bot removed the topic: pyplot API label Mar 11, 2025

This comment was marked as outdated.

Sign in to view

This comment was marked as resolved.

Sign in to view

jayaddison marked this pull request as draft March 11, 2025 13:08

This comment was marked as outdated.

Sign in to view

jayaddison mentioned this pull request Mar 11, 2025

[Bug]: Unit tests: MacOS 14 failures: gi-invoke-error-quark #29732

Open

This comment was marked as outdated.

Sign in to view

github-actions bot added the topic: pyplot API label Mar 11, 2025

This comment was marked as resolved.

Sign in to view

github-actions bot removed the topic: pyplot API label Mar 11, 2025

jayaddison commented Mar 11, 2025

View reviewed changes

lib/matplotlib/tests/test_rcparams.py Outdated Show resolved Hide resolved

github-actions bot added the topic: pyplot API label Mar 12, 2025

jayaddison marked this pull request as ready for review March 12, 2025 19:35

tacaswell added this to the v3.10.2 milestone Mar 12, 2025

TST: coverage of backend fallback in headless mode

2ed08c1

Co-authored-by: Ian Thomas <ianthomas23@gmail.com>

jayaddison force-pushed the issue-29713/auto-backend-case-sensitivity-fixup branch from b07d9c6 to 2ed08c1 Compare March 12, 2025 21:51

ianthomas23 approved these changes Mar 14, 2025

View reviewed changes

ianthomas23 merged commit 309d380 into matplotlib:main Mar 14, 2025
36 of 38 checks passed

meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Mar 14, 2025

Backport PR matplotlib#29721: FIX: pyplot auto-backend detection case…

5090b26

…-sensitivity fixup

meeseeksmachine mentioned this pull request Mar 14, 2025

Backport PR #29721 on branch v3.10.x (FIX: pyplot auto-backend detection case-sensitivity fixup) #29754

Merged

jayaddison deleted the issue-29713/auto-backend-case-sensitivity-fixup branch March 14, 2025 09:31

dstansby added a commit that referenced this pull request Mar 21, 2025

Merge pull request #29754 from meeseeksmachine/auto-backport-of-pr-29…

a56911e

…721-on-v3.10.x Backport PR #29721 on branch v3.10.x (FIX: pyplot auto-backend detection case-sensitivity fixup)

ksunden mentioned this pull request May 9, 2025

merge up 3.10.3 #30031

Open

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FIX: pyplot auto-backend detection case-sensitivity fixup #29721

FIX: pyplot auto-backend detection case-sensitivity fixup #29721

jayaddison commented Mar 9, 2025 •

edited

Loading

jayaddison commented Mar 10, 2025

jayaddison commented Mar 10, 2025

timhoffm left a comment

jayaddison commented Mar 10, 2025

ianthomas23 commented Mar 11, 2025

jayaddison commented Mar 11, 2025

This comment was marked as outdated.

This comment was marked as resolved.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as resolved.

tacaswell commented Mar 12, 2025

nileshpatra commented Mar 13, 2025 via email

ianthomas23 left a comment

jayaddison commented Mar 14, 2025

FIX: pyplot auto-backend detection case-sensitivity fixup #29721

FIX: pyplot auto-backend detection case-sensitivity fixup #29721

Conversation

jayaddison commented Mar 9, 2025 • edited Loading

PR summary

PR checklist

jayaddison commented Mar 10, 2025

jayaddison commented Mar 10, 2025

timhoffm left a comment

Choose a reason for hiding this comment

jayaddison commented Mar 10, 2025

ianthomas23 commented Mar 11, 2025

jayaddison commented Mar 11, 2025

This comment was marked as outdated.

This comment was marked as resolved.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as resolved.

tacaswell commented Mar 12, 2025

nileshpatra commented Mar 13, 2025 via email

ianthomas23 left a comment

Choose a reason for hiding this comment

jayaddison commented Mar 14, 2025

jayaddison commented Mar 9, 2025 •

edited

Loading