Closing the window does not shutdown the app after hot reloading

[Mick235711]

First Check

• I added a very descriptive title here.
• This is not a security issue (those should be reported via the security advisory instead).
• This is not a Q&A. I am sure something is wrong with NiceGUI or its documentation.
• I used the GitHub search to find a similar issue and came up empty.

Example Code

from nicegui import app, ui

def app_startup():
    print('app startup')

def app_shutdown():
    print('app shutdown')

app.on_startup(app_startup)
app.on_shutdown(app_shutdown)

@ui.page('/')
def index():
    ui.button('destroy window', on_click=lambda: app.native.main_window.destroy())
    ui.button('nicegui shutdown', on_click=lambda: app.shutdown())
    
ui.run(
    title="Some app",
    port=8502,
    native=True,
    reload=True,
    window_size=(1920, 1200),
    storage_secret='my secret'
)

Description

Very similar to #2107, but seems to be a different problem (or maybe the original fix is not enough), as the original problem is described to be windows only, but I'm on macOS now.

Specifically, the original issue itself is fixed: open the app, click either X or destroy window or nicegui shutdown, all three actions leads to a proper shutdown of the app even with reload=True. However, when you actually tries to use hot reload, the entire thing is again broken.

Full reproduction steps:

1. Open the app
2. Edit the file to add something irrelevant (like a comment), triggering an auto reload
3. Press X or destroy window, the window closed but the app does not quit (the console is still in the app's process; in fact if you edit the file again the console will show a second hot reload message). Press nicegui shutdown still works properly.

Console output:

NiceGUI ready to go on http://127.0.0.1:8502
app startup
WARNING:  WatchFiles detected changes in 'test.py'. Reloading...
app shutdown
NiceGUI ready to go on http://127.0.0.1:8502
app startup
<Press Ctrl-C>app shutdown

NiceGUI Version

3.8.0

Python Version

3.14.3

Browser

Other

Operating System

macOS

Additional Context

macOS Tahoe 26.3 (arm64) on an M2 Pro MacBook Pro

[chidoziemanagwu]

Hi @Mick235711 , thanks for the detailed reproduction steps.

I'm a Senior Engineer with experience in high-availability Python services, and I've seen this pattern before. It looks like a classic desynchronization between the pywebview native window lifecycle and the uvicorn/watchfiles supervisor process during a hot-reload.

When reload=True is active, the signal from the native window's 'close' event is likely hitting the child worker but failing to propagate to the parent watcher process. I'm currently looking into nicegui/native/native.py to see how we can ensure the shutdown signal reaches the entire process group.

Please assign this to me and I'll attempt a fix and submit a PR soon.

[evnchn]

@chidoziemanagwu we don't really do task assignments, but feel free to take a shot!

I have asked Claude Opus to take a shot at this as well. I'll have it post the results below later. Feel free to base your research off it, though do take it with a huge grain of salt.

[evnchn]

Hi @chidoziemanagwu, welcome! Great to see you jumping in on this. 👋

I'm Claude Code (Claude Opus), asked by @evnchn to take a look at this. Below is my analysis — take it with a grain of salt as suggested, but hopefully it's a useful starting point for your investigation.

Full analysis and proposed fix

Process Architecture (native=True, reload=True)

Process	Role	Started by
Supervisor	Runs ChangeReload, watches for file changes	User's script via ui.run()
Webview	Runs pywebview window (daemon of supervisor)	native_module.activate()
Worker	Runs the actual uvicorn server	ChangeReload (respawned on each reload)

How window-close shutdown normally works

In native_mode.py, activate() starts a check_shutdown() daemon thread in the supervisor process:

def check_shutdown() -> None:
    while process.is_alive():       # monitor the webview process
        time.sleep(0.1)
    Server.instance.should_exit = True
    while not core.app.is_stopped:
        time.sleep(0.1)
    _thread.interrupt_main()         # send SIGINT to supervisor's main thread
    native.remove_queues()

The chain is:

Window closes → webview process exits → check_shutdown() detects process.is_alive() == False
→ _thread.interrupt_main() → supervisor receives SIGINT → ChangeReload.should_exit.set() → clean shutdown

This works on the first run because the webview process exits cleanly when webview.start() returns after the last window closes.

Why it breaks after hot reload

After a hot reload, the webview's page content is reloaded (the server went down momentarily and came back up). On macOS, webview.start() (the Cocoa/AppKit event loop) does not return after the window is closed if the page was reloaded during the session. The window closes visually, the closed event fires, the window_method_executor thread exits — but webview.start() keeps the Cocoa event loop running. The webview process stays alive, so check_shutdown() is stuck forever in while process.is_alive().

This explains why app.shutdown() still works — it bypasses the webview process exit detection entirely:

# app/app.py
def shutdown(self) -> None:
    if self.native.main_window:
        self.native.main_window.destroy()
    if self.config.reload:
        os.kill(os.getppid(), signal.SIGINT)  # Direct SIGINT to supervisor!

Proposed fix

Apply the same direct-SIGINT approach inside the window_method_executor. When the executor detects the window has closed (closed.is_set()), it sends SIGINT to the supervisor — exactly what app.shutdown() does.

--- a/nicegui/native/native_mode.py
+++ b/nicegui/native/native_mode.py
@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import _thread
 import multiprocessing as mp
+import os
 import queue
+import signal
 import socket
 import sys
@@ -65,6 +67,7 @@
 
     def window_method_executor() -> None:
+        supervisor_pid = os.getppid()
         pending_executions: list[Thread] = []
         while not closed.is_set():
             try:
@@ -93,6 +96,13 @@
             except Exception:
                 log.exception(f'error in window.{method_name}')
+        # Notify the supervisor that the window has been closed,
+        # even if webview.start() doesn't return (e.g., on macOS after hot reload).
+        # This mirrors what app.shutdown() does via os.kill(os.getppid(), signal.SIGINT).
+        if supervisor_pid > 1:
+            try:
+                os.kill(supervisor_pid, signal.SIGINT)
+            except (ProcessLookupError, OSError):
+                pass
 
     Thread(target=window_method_executor).start()

Why this is safe

• Reload mode: The SIGINT triggers ChangeReload.signal_handler → should_exit.set() → clean shutdown. This is the case the fix targets.
• Non-reload mode: The SIGINT is redundant (existing check_shutdown() already handles shutdown via _thread.interrupt_main()) but harmless — uvicorn handles SIGINT gracefully.
• Guard supervisor_pid > 1: Prevents accidentally signaling launchd (PID 1) if the parent somehow died first.
• Only fires on actual window close: The executor loop only exits when closed.is_set(). During a hot reload's signal_server_shutdown, closed is NOT set (window stays open), so the SIGINT is not sent.

[chidoziemanagwu]

no problem i will look at it and take it up if i need to

[falkoschindler]

Interesting... Here's an MRE:

from nicegui import app, ui

ui.button('destroy window', on_click=lambda: app.native.main_window.destroy())

ui.run(native=True, reload=True)