How installed PWAs pick up manifest changes

In one line: per web.dev, once a PWA is installed, Chrome periodically re-fetches its web app manifest and compares it against the local copy; changes to a specific set of fields trigger an update, and which fields actually get applied once that update lands differs between desktop Chrome and Chrome on Android.

Where it is supported

Per web.dev’s own note on this page, the documented behavior is Chrome-specific: “We’re still gathering data on browsers other than Chrome.” Everything below describes desktop Chrome and Chrome on Android only, not other browsers or engines.

Updates on desktop Chrome

When the PWA is launched, or opened in a browser tab, Chrome determines the last time the local manifest was checked for changes. If it hasn’t been checked since the browser last started, or not within the last 24 hours, Chrome fetches the manifest and compares it against the local copy. If certain properties changed, Chrome queues the new manifest and installs it after all windows of the app are closed. Once installed, every field from the new manifest is updated except icons — desktop Chrome doesn’t yet support icon updates.

The properties that trigger a desktop update are: name, short_name, display, scope, shortcuts, start_url (changing start_url requires the manifest id to be set), theme_color, and file_handlers.

{
  "id": "/",
  "name": "My App",
  "start_url": "/app/v2/",
  "theme_color": "#0b5fff"
}

web.dev notes that if you change display from browser to standalone, existing users won’t have their open app suddenly switch to a window — the window/tab setting a user already chose is always respected.

Updates on Chrome for Android

Android follows the same 24-hour check cadence, but the rollout differs: after a changed manifest is queued, Chrome waits until all windows of the PWA are closed and the device is plugged in and connected to Wi-Fi before requesting an updated WebAPK from the server. Once that WebAPK arrives, every field from the new manifest is used — including icons, which desktop Chrome cannot yet update.

The properties that trigger an Android update are: name, short_name, icons, background_color, display, orientation, scope, shortcuts, start_url, theme_color, and web_share_target. If Chrome can’t reach the server for an updated manifest, it may back off and check as infrequently as once every 30 days.

How to detect it at runtime

web.dev’s guide describes checking manifest-update information through two browser-internal diagnostic pages. The display-mode media feature is a standardized signal a page can test, but per MDN it reports the actual display mode of the top-level browsing context, not whether a manifest update has landed:

if ('matchMedia' in window && window.matchMedia('(display-mode: standalone)').matches) {
  // The top-level browsing context's actual display mode is standalone.
  // This says nothing about whether the manifest was re-checked or updated.
} else {
  // matchMedia is unavailable, or the actual display mode is not standalone.
  // Fall back without inferring a browser tab or a manifest-update state.
}

Per web.dev, Chrome checks for manifest changes “whenever a PWA is launched, even if it’s opened in a browser tab,” so a page’s display mode has no bearing on whether an update check happened.

To inspect update state using the methods web.dev describes, use the browser-provided diagnostic pages:

• On desktop Chrome (85+), chrome://web-app-internals “includes detailed information about all of the PWAs installed on the device,” including when a given app’s manifest was last checked and how often it’s updated, per web.dev.
• On Chrome for Android, about://webapks gives the same kind of detail for installed WebAPKs, and shows an “Update Status” field, per web.dev.

Open the appropriate internal page manually to inspect the manifest-update information that web.dev describes.

Practical checklist

• Don’t rename or move your manifest file — web.dev’s own caution notes that doing so “may prevent the browser from updating your PWA.”
• Expect changes to show up “within a day or two” in most cases, per web.dev, since both platforms check on a roughly 24-hour cadence rather than instantly.
• On desktop, icon changes are not yet applied at all; only Android’s WebAPK rebuild picks up a new icons list.
• Changing start_url on desktop only takes effect once the manifest also declares an id — see the id reference below.
• To test updates, use chrome://web-app-internals (desktop, Chrome 85+) to see when a manifest was last updated and how often it’s updated, or about://webapks (Android) to see the update status.

Where to go next

• Web app manifest id: a stable PWA identity
• Manifest start_url

Specifications

Specification	Status
None.