PWAs on a Mac not working: what to check, in order

Installing a website as an app on a Mac fails in a small number of ways, and each way has a distinct fingerprint. The trouble is that the fingerprints look alike from the outside. A missing menu item, a missing badge in the address bar, an app that opens but shows a login screen, and an app that never makes a sound all get described the same way: it did not work. Sorting them takes about five minutes if the checks run in the right order, because each layer depends on the one before it. Running them out of order produces the common outcome where a setting gets changed, nothing improves, and the change stays in place making the next test harder to read.

Check the symptom before checking anything else

The fastest split is whether the app exists yet.

If no icon was ever created, the problem is in the install path: the command is missing, the badge never appeared, or the confirmation dialog was dismissed. If an icon exists and misbehaves, the install path worked and the problem is in what the app inherited: session data, permissions, or which browser owns it.

That split matters because the two halves have no fixes in common. Time spent clearing caches will never bring back a menu item that the operating system version does not include, and reinstalling will never fix a notification permission that was answered in the wrong window.

Symptom	Layer	Where the fix lives
No install command anywhere	macOS version or browser choice	System requirements
Command present, badge never appears	Site manifest or install state	The site, or the menu item that bypasses the check
Installs, then opens as a browser tab	Display mode or how it was launched	Manifest display value
Opens to a login screen	Session data that did not transfer	Sign in once inside the app
No notifications, no badge	Permission answered in the wrong window	The prompt, answered inside the app
Icon cannot be found	Save location	Applications folder inside the home folder

Work down the table. Each row assumes the rows above it are clear.

The install command is missing from the menu

Two conditions produce this, and both are absolute rather than negotiable.

The first is the macOS version. Apple's documentation states that creating a web app from a webpage requires macOS Sonoma 14 or later. On anything earlier, File then Add to Dock does not exist in Safari, and no setting brings it back. That is the end of the Safari route on that machine.

The second is the browser. Firefox on macOS has no equivalent command. MDN's reference states that Firefox requires a PWA extension for this, and the browser's own web app feature has not reached macOS. Anyone who reads a general guide about installing a PWA and then looks for the option in Firefox on a Mac will find nothing, because the option is not there to find.

In Safari, the command appears in two places: File then Add to Dock in the menu bar, or the Share button in the toolbar then Add to Dock. In Chrome the path is the three dot menu at the top right, then Cast, save, and share, then Install page as app. Older articles describe a Create shortcut command with an Open as window checkbox. That item was replaced, and looking for the checkbox in a current version of Chrome is a dead end. The replacement always produces a window.

If the goal is reachable from either browser, check which one is actually in front before concluding the feature is missing. Reading a Safari instruction while looking at a Chrome window accounts for a large share of these reports.

The install badge never appears in the address bar

This is the Chromium specific case, and it is worth separating from the one above because the command still works. What is missing is the automatic prompt.

Chrome shows the install icon in the address bar only when the site passes an installability check. The published requirements are an icons entry containing both a 192 by 192 pixel and a 512 by 512 pixel icon, a start_url, a display value of fullscreen, standalone, or minimal-ui, and prefer_related_applications set to something other than true. The page must be served over HTTPS. A site missing any of these will never surface the badge no matter how long the page stays open.

Three further reasons produce the same silence on a site that does qualify. The check itself takes a moment, so the badge can appear a second or two after the page finishes loading rather than with it. The site may already be installed in this browser, in which case the badge is replaced by an open command. And the install belongs to the browser profile, so a site installed in a work profile shows as not installed in a personal profile on the same Mac.

None of this blocks progress. Chrome's menu item installs a site that fails the check, producing what Chrome's documentation calls a manual app rather than a PWA install. The practical difference is that the app takes its name and icon from the page rather than from a manifest, so both are worth setting deliberately afterwards.

It installed, but opens in a tab or in the wrong kind of window

Two different faults share this description.

The first is display mode. Only standalone and minimal-ui are supported as display modes on desktop operating systems. A manifest requesting fullscreen falls back to something else, and a manifest requesting browser is asking for a tab, which is exactly what it will get. On the Safari route this is less common, because Safari opens a web app in its own window even when the site publishes no manifest at all.

The second is launch method. An app opened from the Dock, from Spotlight, or from the application switcher opens as an app. A link to the same address clicked inside mail or chat opens the default browser instead, because macOS routes URLs by protocol and an installed web app does not register itself as the handler for https. The app is working correctly. The link simply never reached it. Anyone whose daily work arrives as links from other people will see this constantly and read it as a broken install.

A related complaint is a window that opens at the wrong size or on the wrong display every time. That is not a fault of the install. Window position is remembered per app, so moving it once and quitting with Command Q writes the new position.

A third variant looks like a tab but is not one. Some sites open a second window as part of a normal action: a document preview, a report, a sign in step handled in a popup. In a standalone window that child window arrives with no toolbar and no obvious way back, which reads as the app having broken. Nothing is broken. The popup has nowhere to put its controls. Safari's web app settings include a Show navigation controls switch, and turning it on restores back, forward, and share to the toolbar, which is usually enough to escape. On the Chromium route the equivalent is the three dot menu inside the app window.

It opens to a login screen

An app that demands a sign in immediately after being created is behaving as designed, and the reason is worth understanding because it decides whether signing in once is enough.

Safari copies the site's cookies into the new web app at the moment of creation, and copies nothing else. Any state the site kept in local storage, IndexedDB, or a service worker cache stays in Safari. Sites that reconstruct a session from cookies alone come across signed in. Sites that store a token outside cookies do not. Signing in once inside the app window is the fix, and from that point the app keeps its own session independently of the browser.

The Chromium route inverts the relationship. An app installed from a Chrome profile shares that profile's storage, so it starts out signed in, and signing out in the browser signs out the app as well. That is convenient until two accounts are involved. Separating a work login from a personal one on this route means creating a second Chrome profile first and installing the app from inside it.

An app that signs itself out repeatedly, days after installation, is a third case. Check whether a cleanup utility or a privacy setting is clearing cookies on a schedule. Safari's web app settings include a Privacy tab that can clear the site's data including cookies and caches, which is easy to trigger while looking for something else.

Notifications and badges never arrive

This one has a single cause often enough to check it first among permission problems.

Apple's documentation is explicit that the unread count on the Dock icon requires the notification permission to be answered in the web app rather than in Safari. A site that was already granted permission in the browser does not carry that grant into the app. The prompt has to appear inside the app window and be accepted there.

The confirmation is in System Settings. Open Notifications in the sidebar and look for the app in the list on the right. Apple notes that web apps are listed under the name of the web app, not the URL of the website, so scanning for a domain will miss it. An app that is absent from that list has never been granted the permission, whatever the browser shows.

Two conditions can hide an otherwise correct setup. Focus modes suppress delivery without changing any permission. And a site that delivers notifications through a service worker needs that worker running, which for some sites means the app has to have been opened at least once since the Mac last restarted.

The icon cannot be found, or there are two of them

Safari saves a web app to the Applications folder of the home folder, which is not the Applications folder at the root of the disk. Both are named Applications, both appear in Spotlight, and only one is what most people open in the Finder. An app that seems to have vanished is usually sitting in the other one. That location is also where the bundle has to be dragged from to delete it.

Duplicates come from the browser boundary. A browser will not install the same site twice, but two browsers each will, and the two results share no data. Installing from Safari after an earlier install from Chrome produces two icons for one service, each with its own session, and the pair are indistinguishable at small Dock sizes because they carry the same favicon. Renaming one and changing its icon is faster than working out afterwards which window holds which account.

Removal differs by route as well. A Safari web app goes to the Trash from the home folder. A Chrome app is removed from inside its own window through Uninstall, and the dialog offers a separate checkbox for deleting the site data from Chrome, which is not selected by default.

What to change first

Work the table from the top and stop at the first row that matches, because fixes applied below a real fault only add variables. Once the app is running, the two settings worth getting right immediately are its name and its icon, covered in the Guide, since those are what prevent the duplicate problem later. For sites where the browser routes keep running into the same wall, Kagemusha lists what a dedicated tool handles instead.