Convert macOS backend to ARC by iccir · Pull Request #31855 · matplotlib/matplotlib

iccir · 2026-06-07T18:08:25Z

PR summary

This pull request enables Automatic Reference Counting for the macOS backend.

Closes #21788
Closes #27147 (Assuming show(block=False) is called)
Closes #29076
Closes #31797
Closes #31798
Closes #32019

I'm still testing this PR on macOS 10.12, macOS 14, and macOS 26. I wanted to start the PR process early so that others could review my general direction and give opinions.

Note

I'm trying to follow existing coding styles already present in _macosx.m. However, this pull request converts some Objective-C instance variables (ivars) to Objective-C properties, which adds an underscore to the ivar name.

I'd like to convert more of these in the future, especially in View where there is a @public ivar (ivar scoping attributes like @public haven't been used for a very long time).

If there are any concerns, or if I'm overstepping, please let me know!

ARC C Struct Compatibility

As we support compiling on macOS 10.12, we cannot use ARC objects within C structures. Support for this was added in Xcode 10 / macOS 10.14. See WWDC 2018 Session 409 for more information about this:
Archived Video (Direct 1.3GB download)
Archived Slides

As a workaround, I added a new macro called STORE_OBJC_OBJECT which manually performs reference counting when storing into structs allocated with tp_alloc.

The basic pattern for dealing with Python/Obj-C objects and using this macro is as follows:

typedef struct {
    PyObject_HEAD
    __unsafe_unretained MyObjCObject* myObjCObject;
} MyPythonObject;


static PyObject*
MyPythonObject_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    BEGIN_OBJC_ENTRY

    MyPythonObject *self = (MyPythonObject*)type->tp_alloc(type, 0);
    return (PyObject*)self;

    END_OBJC_ENTRY
    return NULL;
}

static PyObject*
MyPythonObject_init(MyPythonObject *self, PyObject *args, PyObject *kwds)
{
    BEGIN_OBJC_ENTRY

    MyObjCObject *myObjCObject = [[MyObjCObject alloc] init];
    [myObjCObject setPythonObject:self]; // See below section, back-pointer
    STORE_OBJC_OBJECT(self->myObjCObject, myObjCObject);

    END_OBJC_ENTRY
    return 0;
}

static void
MyPythonObject_dealloc(MyPythonObject *self)
{
    BEGIN_OBJC_ENTRY

    [self->myObjCObject setPythonObject:NULL]; // Clear back-pointer
    STORE_OBJC_OBJECT(self->myObjCObject, nil);

    END_OBJC_ENTRY
    Py_TYPE(self)->tp_free((PyObject*)self);
}

If, someday, our minimum target for building matplotlib becomes macOS 10.14 / Xcode 10, then the following changes would occur:

typedef struct {
    PyObject_HEAD
    __strong MyObjCObject* myObjCObject; // Now an ARC'd strong pointer
} MyPythonObject;


static PyObject*
MyPythonObject_init(MyPythonObject *self, PyObject *args, PyObject *kwds)
{
    …
    self->myObjCObject = myObjCObject; // Can assign directly!
    …
}

static void
MyPythonObject_dealloc(MyPythonObject *self)
{
    …
    self->myObjCObject = nil; // Needs to be nil before tp_free()
    …
}

This assumes that tp_alloc() is using PyType_GenericAlloc, which zero-fills allocated memory.

Paired +alloc and -init

This PR correctly pairs each call to +alloc with an immediate call to -init…. See #31798 for more information on this.

Ownership Overview

Based on my previous experience working with language bridging, I think the following ownership structure makes sense:

Each PyObject should own an Obj-C object via a strong reference.
The Obj-C object, if needed, should have a weakly-assigned back-pointer to the PyObject. This back-pointer should be set in Foo_init and must be cleared in Foo_dealloc.
In modern Objective-C, you would use a readwrite + assign @property for the back-pointer variable:

@property (nonatomic, readwrite, assign) PyObject *myPythonObject;
or simply:
@property (nonatomic) PyObject *myPythonObject;

This will automatically create a backing _myPythonObject ivar as well as a -setMyPythonObject: method.

FigureManager and Window

As mentioned in my last PR, FigureManager and Window strongly reference each other. I believe this is for historical reasons, likely to prevent a crash.

I made Window weakly-reference FigureManager to follow the pattern established in other objects and haven't experienced any issues. That said, I'm still wrapping my head around the interactions between Python and the main NSRunLoop.

I changed Window's raw manager ivar to a property. This synthesized a setManager: method and eliminated the need for declaring our own -init… method.

There is a new FigureManager__closeAndClearWindow() method called from FigureManager_destroy and FigureManager_dealloc. It needs to be called from both since Windows are fairly heavyweight objects and we should probably release the memory as soon as they are closed. This method zeros-out back-pointers.

NavigationToolbar2Handler

The -init… method is no longer needed since the pointer to NavigationToolbar2 is now a readwrite property.

There was a potential crash if the NavigationToolbar2 was freed and then NavigationToolbar2Handler tried to access it. The back-pointer needs to be cleared in NavigationToolbar2_dealloc to prevent this.

Modern practice is to place additional ivars directly on the @implementation block. You can also use @property syntax and make them readonly. I did the latter here so we could get rid of the @interface ivars.

View

-[View initWithFrame:] needs to check that the call to super succeeds. In the very-rare case that -[NSView initWithFrame:] returns nil, we were trying to dereference a NULL pointer. The if (self = [super init…]) { pattern is standard practice.

It's also standard practice for -init… methods to use instancetype as the return type. This is mostly to handle subclassing, so it's not actually needed here, but I figured that it was best to change it.

Clearing a weak back-pointer in -[View dealloc] isn't doing what it appears to do. These always need to be cleared by the owning object in the owning object's dealloc/ThePyObject_dealloc methods.

The rest of the changes involve removing setCanvas:, as it is synthesized, and using the synthesized ivar for the canvas @property instead of the old directly-declared one.

Timer

I fixed #29076 while I was testing Timer invalidation and ownership.

Timer__timer_stop_impl had to be moved so Timer__timer_start could call it.

AI Disclosure

I used AI to ask for advice about how tp_alloc works and if it zero-fills memory.
No code was modified by AI, nor did I use any code suggested by AI.

PR checklist

"closes #0000" is in the body of the PR description to link the related issue
new and changed code is tested
[N/A] 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

greglucas · 2026-06-08T02:24:32Z

Overall this looks like a good direction to me. I would say that most people who have written/contributed to the macos backend are not objc developers, so we (at least myself) are likely just not aware of the objc conventions and patterns. Please feel free to correct things you think would make this easier to understand/follow. Your explanations so far have been really great, so thank you for that and the links for references, I've been learning myself!

I think we should bump our minimum supported deployment target to 10.14 at a minimum for our new releases. It has been unsupported by Apple for nearly 5 years now.
https://endoflife.date/macos

Python 3.12-13 already have a 10.13 (3.14 has a 10.15) minimum when building wheels, so we might not even be getting 10.12 support even if we're trying to declare it. Apple Silicon requires 11+
https://cibuildwheel.pypa.io/en/stable/platforms/

If this makes the code more reliable and easier to maintain in the future, we should do it now IMO. Moving all in on ARC and not requiring the extra manual reference counting macros looks much nicer to me.

Some links on stats from other main Python discussions for reference as well, showing this is a really small number of people to support on that old of an XCode / OS.
https://discuss.python.org/t/macos-version-support-policy/53715/21
https://discuss.python.org/t/moving-packaging-and-installers-to-macos-10-13-as-a-minimum/31907/8

iccir · 2026-06-08T03:47:12Z

Python 3.12-13 already have a 10.13 (3.14 has a 10.15) minimum when building wheels, so we might not even be getting 10.12 support even if we're trying to declare it. Apple Silicon requires 11+ https://cibuildwheel.pypa.io/en/stable/platforms/

10.12 and 10.13 have broken installers, as well. They are installable, but require jumping through flaming hoops:

There are also some new methods added in Mojave (10.14) related to View's device_scale math, so bumping to 10.14 may have some additional benefits.

iccir · 2026-06-09T19:30:46Z

I spent yesterday and today trying to wrap my head around the interactions between the various event-loop-related APIs and how they interact with our use of NSRunLoop. My ultimate goal was making sure that both calls modifying FigureWindowCount occcurred at the same architectural level.

There was a bit to unpack :)

Ideal Architecture

First, an NSView should not be the delegate of its window, as a window has strong ownership of its views.

Generally, you would have something like an NSWindowController or another controller-level object own a window (strong reference) and that object be the window's delegate window (weak reference).

In a larger-scale system with lots of bridged object types, you would probably have each PyModule *Type linked to a similarly-named Objective-C class which then uses Cocoa objects. Something like this:

PyModule Type	Obj-C Class	Owns / Uses
FigureManagerType	MPLFigureManager	NSWindow
FigureCanvasType	MPLFigureCanvas	NSView
NavigationToolbar2Type	MPLNavigationToolbar	NSButton, NSTextField, etc.
TimerType	MPLTimer	NSTimer

In our smaller-scale system, a lot of this would be overkill!

TimerType is fine using an NSTimer directly. While the object owned by FigureCanvasType should probably be called MPLFigureCanvas, it likely needs to be an NSView in order to participate in AppKit's responder hierarchy.

In any case, the "FigureManager" concept should own the window and be its delegate. It's not possible to have FigureManagerType directly be a delegate since it's not an Obj-C class, so we will need an intermediary MPLFigureManager. That's for the next refactor, however!

With that said, on to the latest changes:

FigureWindowCount

The FigureWindowCount static variable is now directly tied to how many FigureManagers still have windows. It is managed by the FigureManager_* functions rather than being incremented at one level and decremented in -[Window close].

There needs to be a new IsRunningFromShow boolean to keep track of whether or not closing the last window should call -[NSApp stop:].

-[View windowWillClose:]

-windowWillClose: is always called when a window is about to close (whether initiated from a user action or programatically).

This method was directly posting a close_event. This is needed to properly clean up the subplot tool (see configure_subplots() in backend_bases.py).

For now, I'm calling a new FigureManagerMac._handle_window_will_close in backend_macosx.py which posts the close_event from the Python level. This change will hopefully make sense in the next section.

-[View windowShouldClose:]

-windowShouldClose: is called when the user clicks the close button, selects the "File -> Close" command in the menu bar, or performs the ⌘W keyboard shortcut.

Note

⌘W is currently handled by our own key bindings and bypasses -windowShouldClose:

Based on code analysis, I was confused as to why FigureCanvas__start_event_loop() wasn't breaking when this method was invoked, since we are posting an NSEventTypeApplicationDefined-type event. I'm still not sure, I think it had to do with event ordering and/or run loop modes. That said, the end result was that closing a window didn't break out of the loop. Per @timhoffm 's comment in #31858, this sounds like the correct behavior.

Thus, the NSEvent posting in -[View windowShouldClose:] can go away as it was not doing anything.

-[Window closeButtonPressed] was calling "_close_button_pressed" at the Python level and then always returning YES. That's a bit weird per Objective-C naming conventions, as -closeButtonPressed sounds like an accessor method.

Instead, I'm calling FigureManagerMac._handle_window_should_close. This Python method used to be called FigureManagerMac.closed_button_pressed; however, that's not an ideal name as it can be invoked in response to other UI elements (not just the close button).

greglucas

This looks great to me and makes sense what is going on with all the updates. Thank you for taking the time to write it out and explain it as well.

iccir · 2026-06-13T15:46:02Z

@greglucas - I thought that I found a potential crash and pushed a fix, so you probably need to re-review.

-[View convertKeyEvent:] was creating an NSString called returnkey and then returning a C string buffer owned by that NSString.

Under non-ARC, this was fine. returnkey was in the autorelease pool and wouldn't be released until after keyDown: or keyUp: execute.

Under ARC, returnkey would normally be immediately released when it goes out of scope. -[NSString UTF8String] is marked as objc_returns_inner_pointer, so the lifetime is extended.

I couldn't remember the exact details of the lifetime extension and the documentation was unclear to me. On my machine (Sonoma, Xcode 15), the compiler transforms it into a -retain/-autorelease pair:

objc_msgSend(objc_retainAutorelease(returnkey), "UTF8String"));

I'm still not sure if this is guaranteed, or if -convertKeyEvent: needs to also have the inner pointer attribute. In any case, I think it's best for readability to return an NSString and let -keyDown:/-keyUp: perform the C string conversion.

greglucas

The new commit is minor and this all looks good to me still 👍

iccir · 2026-06-20T16:34:39Z

I've been testing on macOS 10.14 + Python 3.13 + Xcode 11.3.

I haven't found any crashers with when running with NSZombies. Nor have I found any memory leaks.

However, when I run pytest, I get:

====== 1 failed, 6285 passed, 1596 skipped, 29 xfailed, 1 xpassed, 11 warnings, 2508 errors in 1112.57s (0:18:32) =======

The 1 failure looks legitimate as the test is checking the count of close_events.

I'll investigate.

Sonoma and Tahoe had some failed test related to timeouts, but after re-running the tests in question several times I couldn't reproduce.

iccir · 2026-06-21T03:20:32Z

After more investigation, the failure was:

.venv/lib/python3.13/site-packages/_pytest/fixtures.py:1221: AssertionError
======================================================= FAILURES ========================================================
______________ test_interactive_thread_safety[MPLBACKEND=macosx-BACKEND_DEPS=matplotlib.backends._macosx] _______________
[XPASS(strict)]

From my understanding, XPASS(strict) means that it passed, but it was expected to fail.

The relevant code in test_backends_interactive.py was added by @QuLogic :

    elif backend == "macosx":
        from packaging.version import parse
        mac_ver = platform.mac_ver()[0]
        # Note, macOS Big Sur is both 11 and 10.16, depending on SDK that
        # Python was compiled against.
        if mac_ver and parse(mac_ver) < parse('10.16'):
            param.marks.append(
                pytest.mark.xfail(raises=subprocess.TimeoutExpired,
                                  strict=True))

I suspect that a recent change fixed this in Mojave and Catalina. In any case, I'm now confident with this PR as I have tested in 10.14, 14.7, and 26.5.

# Conflicts: # .github/workflows/cibuildwheel.yml

iccir · 2026-06-27T17:42:48Z

@QuLogic - Can you link #21788 and #31798 to this PR so they get closed when it merges?

Additionally, I need another reviewer to get this merged. Is that something you can do? Let me know if there's anything else that I need to do on my end! Thanks!

timhoffm · 2026-06-28T04:58:47Z

@QuLogic - Can you link #21788 and #31798 to this PR so they get closed when it merges?

You can do this yourself via keywords in the original post. You need a keyword per issue. - I've now done this for you by editing the post. Note: "Closes, A, B and C" does not work. You need "Closes A, closes B, closes C".

- Add a weak-objects hash table to keep track of active `Window` objects. - Check `[FigureWindowHashTable count]` instead of `FigureWindowCount` - Iterate over said hash table in `show()` rather than using `NSApplication.windows`

iccir · 2026-07-10T03:20:06Z

The crash portion of #32019 is already fixed by this PR. I'm adding a fix for the rest of #32019. As far as I can tell, GitHub doesn't allow marking a pull request as dependent on another pull request. If there is a better way, please let me know.

The root cause of #32019 is that AppKit is holding a strong reference to our Window. This is likely due to a block-capture from a dispatch_async invocation, but we have no way of knowing for sure. We do know that we are properly clearing our own strong reference and that AppKit's extra strong reference is cleared after a few seconds.

However, if show() is called again soon after the last window closes, NSApplication.windows still contains the old window. We then try to display that window during the second show() call.

The updated PR replaces FigureWindowCount with FigureWindowHashTable. This is a weakObjectsHashTable that holds our active Window objects. We then iterate over this hash table in show().

jklymak

I won't pretend to know what this does, but dont' see anything malicious ;-). @greglucas there have been some changes since your review. Suggest you take a quick look and then merge if happy. This seems to fix a tonne of macosx windowing bugs

iccir · 2026-07-10T17:33:39Z

I won't pretend to know what this does, but dont' see anything malicious ;-)

@jklymak - Always happy to explain, if you ever feel the need to dive into the depths of Obj-C land ;)

Note that this patch will change the minimum requirements to macOS 10.14 Mojave (released in 2018). Our previous minimum requirement was macOS 10.12 Sierra (released in 2016). I'm not sure what steps need to be taken to document this for release notes, but I'm happy to make those changes too if you point me in the right direction.

jklymak · 2026-07-10T18:00:40Z

I think it just needs to be in the release notes. I'm not sure our policy on supporting old OS'es but 10.12 is ancient and folks have the ability to use old matplotlib and/or other backends. I think modernizing to a 2018 release is easily justified.

greglucas · 2026-07-24T03:17:18Z

Thanks for taking this across the line @iccir, this is something I've been looking forward to!

iccir · 2026-07-24T03:18:21Z

@greglucas - Thank you for merging!

QuLogic · 2026-07-24T03:27:08Z

 test-environment = "PIP_PREFER_BINARY=true"

 [tool.cibuildwheel.macos.environment]
-MACOSX_DEPLOYMENT_TARGET = "10.13"


If this is a new requirement, it needs an API note; see #32061

@QuLogic - Got it, I'll make a PR.

Convert macOS backend to ARC

e11758b

github-actions Bot added the GUI: MacOSX label Jun 7, 2026

Assume minimum version of macOS 10.14

8fd5e75

github-actions Bot added the CI: Run cibuildwheel Run wheel building tests on a PR label Jun 8, 2026

Rework window closing

605ced1

greglucas approved these changes Jun 12, 2026

View reviewed changes

Comment thread src/_macosx.m Outdated

iccir added 2 commits June 11, 2026 20:27

Remove stray log.

dc57723

Fixing potential crash with -convertKeyEvent:

fc570ac

greglucas approved these changes Jun 14, 2026

View reviewed changes

github-actions Bot added the status: needs rebase label Jun 26, 2026

iccir added 2 commits June 27, 2026 09:15

Merge remote-tracking branch 'origin/main' into arc

f3752dc

# Conflicts: # .github/workflows/cibuildwheel.yml

MACOSX_DEPLOYMENT_TARGET to 10.14

d9fd9ba

github-actions Bot removed the status: needs rebase label Jun 27, 2026

iccir mentioned this pull request Jun 27, 2026

[MNT]: Remove macOS 10.12 compatibility from ft2font_wrapper #31963

Closed

This was referenced Jul 8, 2026

[Bug]: Embedded Python uncatchable hard exit on closing last matplotlib window. #27147

Closed

[Bug]: macosx backend, plots not closing, segfault #32019

Closed

Adding additional fix for matplotlib#32019

80a4327

- Add a weak-objects hash table to keep track of active `Window` objects. - Check `[FigureWindowHashTable count]` instead of `FigureWindowCount` - Iterate over said hash table in `show()` rather than using `NSApplication.windows`

jklymak approved these changes Jul 10, 2026

View reviewed changes

QuLogic mentioned this pull request Jul 18, 2026

Bump minimum macOS to 10.13 #32061

Merged

3 tasks

github-actions Bot added the status: needs rebase label Jul 19, 2026

Merge branch 'main' into arc

213618b

github-actions Bot removed the status: needs rebase label Jul 24, 2026

greglucas merged commit 7bd336a into matplotlib:main Jul 24, 2026
41 of 44 checks passed

QuLogic added this to the v3.12.0 milestone Jul 24, 2026

QuLogic reviewed Jul 24, 2026

View reviewed changes

iccir mentioned this pull request Aug 1, 2026

macOS backend rework, initial PR #32161

Open

3 tasks

iccir deleted the arc branch August 13, 2026 15:18

Uh oh!

Uh oh!

Conversation

iccir commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR summary

ARC C Struct Compatibility

Paired +alloc and -init

Ownership Overview

FigureManager and Window

NavigationToolbar2Handler

View

Timer

AI Disclosure

PR checklist

Uh oh!

greglucas commented Jun 8, 2026

Uh oh!

iccir commented Jun 8, 2026

Uh oh!

iccir commented Jun 9, 2026

Ideal Architecture

FigureWindowCount

-[View windowWillClose:]

-[View windowShouldClose:]

Uh oh!

greglucas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

iccir commented Jun 13, 2026

Uh oh!

greglucas left a comment

Choose a reason for hiding this comment

Uh oh!

iccir commented Jun 20, 2026

Uh oh!

iccir commented Jun 21, 2026

Uh oh!

iccir commented Jun 27, 2026

Uh oh!

timhoffm commented Jun 28, 2026

Uh oh!

iccir commented Jul 10, 2026

Uh oh!

jklymak left a comment

Choose a reason for hiding this comment

Uh oh!

iccir commented Jul 10, 2026

Uh oh!

jklymak commented Jul 10, 2026

Uh oh!

Uh oh!

greglucas commented Jul 24, 2026

Uh oh!

iccir commented Jul 24, 2026

Uh oh!

QuLogic Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iccir Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

iccir commented Jun 7, 2026 •

edited

Loading

QuLogic Jul 24, 2026 •

edited

Loading