--- title: "FAQ" description: "Short answers about Code Push: releases and patches, app store guidelines, supported platforms and Flutter versions, what is sent to Shorebird, and billing." --- Short answers to common questions about Shorebird Code Push, each with a link to the page that covers it in full. For an error message or a patch that didn’t install, see [Troubleshooting](/code-push/troubleshooting/). Still have a question? Reach out on [Discord](https://discord.gg/shorebird) or [file an issue](https://github.com/shorebirdtech/shorebird/issues). ## Getting started ### How do you sign in to Shorebird? With a Google or Microsoft account, personal or work (Google Workspace or Microsoft Entra ID). Your first sign-in creates your account. There is no email-and-password sign-in. On the Enterprise plan, members can sign in through your company’s identity provider with [SAML SSO](/enterprise/saml/). Your account keeps signing in with the method you first used. See [Change how you sign in](/account/access-and-ownership/#change-how-you-sign-in). ### What is the difference between a patch and a release? A release is a build you publish to the stores. `shorebird release` builds it and uploads a copy to Shorebird, so later patches can be made against it. A patch updates the Dart code of one release on devices that already have it. `shorebird patch` builds it from your current code. See the [Overview](/code-push). ### When should you create a patch vs a release? A patch changes only Dart code, and only for one release version. Native code, assets and the Flutter version need a new release. Teams commonly patch often (daily or weekly) and release to the stores less often (monthly), or patch only for urgent fixes. Many ship a fix as a patch and in the next store release at the same time, so new installs get it on first launch. See [Is your change patchable?](/code-push/#is-your-change-patchable) ### Can you use Shorebird in your CI system? Yes. Create an API key in the [Shorebird Console](https://console.shorebird.dev) under **Account → API Keys**, then add it to your CI environment as `SHOREBIRD_TOKEN`. See the [CI setup guide](/code-push/ci/generic/) for detailed instructions. ### Can you use Dart defines with Shorebird? Yes. `shorebird release` and `shorebird patch` pass `--dart-define` and `--dart-define-from-file` to Flutter, for example `shorebird release android --dart-define=MY_DEFINE=foo`. Dart defines are compiled into your Dart code, so a patch can change them. ### How do you target different API environments (e.g., staging vs. production backend) for patches? Use Flutter flavors, or `--dart-define` values. Each flavor has its own app ID in `shorebird.yaml`, so `shorebird patch android --flavor development` reaches only devices running the `development` build. See [Apps with flavors](/code-push/guides/flavors/). To test a patch before your users get it, see [Tracks](/code-push/tracks/). ### How does Shorebird relate to Flutter? Shorebird builds your app with its own fork of Flutter, which adds the updater to the Flutter engine. You keep using Flutter’s tooling, and Shorebird tracks Flutter’s stable releases. Because Shorebird downloads its engine from `download.shorebird.dev`, Flutter prints: ``` Flutter assets will be downloaded from http://download.shorebird.dev. Make sure you trust this source! ``` See [System Architecture](/code-push/system-architecture) for why Shorebird forks Flutter. ### Can I use Shorebird with my own fork of Flutter? Not today. `shorebird` always builds with Shorebird’s own copy of Flutter, so changes your team has made to the Flutter framework or engine are not included. Shorebird can port its changes to your fork as a paid offering; [contact Shorebird](mailto:contact@shorebird.dev) to talk it through. ### What platforms does Shorebird support? Android, iOS, macOS, Windows and Linux. On Android, `shorebird release` builds for arm32, arm64 and x86\_64 by default, so x86\_64 devices such as Chromebooks get patches too. You choose per platform: for example, you can ship Android with `shorebird release` and iOS with `flutter build`. See the [platform feature support matrix](/code-push/#platform-feature-support-matrix). ### Does Shorebird work on iOS Simulators? No. On iOS, a patch’s changed code runs in Shorebird’s interpreter, which is built for physical arm64 iOS devices, so patches don’t install on the iOS Simulator. Test iOS patches on a physical device. Android emulators work. ### Does Shorebird work in debug or profile mode? No. Shorebird is only active in release builds. In debug and profile builds, such as `flutter run`, your app uses Flutter’s standard engine, so hot reload and DevTools work as usual. To test a patch, use a build from `shorebird release` or `shorebird preview`. ### What OS versions does Shorebird support? The same ones Flutter supports. See Flutter’s [supported platforms](https://docs.flutter.dev/reference/supported-platforms). ### What versions of Flutter does Shorebird support? Stable Flutter releases. Quarterly minor releases are added within 5 business days of their release, and patch releases within 1 business day. See [Flutter versions](/getting-started/flutter-version/) for the versions by platform. ### Can you use Shorebird with Flutter pre-release channels (Beta, Master)? No. Shorebird only supports **stable** Flutter releases. Shorebird builds with its own copy of Flutter, so the channel your own Flutter is on doesn’t matter unless you pass `--flutter-version=system` or `--flutter-version=fvm`. Asking for a version Shorebird doesn’t have fails with: ``` Flutter is not available to Shorebird. To request it, open an issue at https://github.com/shorebirdtech/shorebird/issues/new. ``` Run `shorebird flutter versions list` to see the versions you can use. ### How do you upgrade the Flutter version of your app? Create a new store release; a patch can’t change a release’s Flutter version. `flutter upgrade` doesn’t change the version Shorebird uses. Pass `--flutter-version=` to `shorebird release`, or leave it out to use the version your installed Shorebird ships, and publish the new build. Patches for that release are built with its Flutter version. See [Use a different Flutter version](/getting-started/flutter-version/#use-a-different-flutter-version). ## Store compliance ### Does Shorebird comply with Play Store guidelines? Yes. Google Play’s [Device and Network Abuse policy](https://support.google.com/googleplay/android-developer/answer/9888379) says: > An app distributed via Google Play may not modify, replace, or update itself using any method other than Google Play’s update mechanism. Likewise, an app may not download executable code (such as dex, JAR, .so files) from a source other than Google Play. *This restriction does not apply to code that runs in a virtual machine or an interpreter* where either provides indirect access to Android APIs (such as JavaScript in a webview or browser). (Emphasis added.) Shorebird patches run in the Dart virtual machine. Google Play also requires that updates not be [deceptive](https://support.google.com/googleplay/android-developer/answer/9888077), such as changing the app’s purpose, so be clear with your users about what your app does. Deliberately using Shorebird to break store guidelines violates Shorebird’s [Terms of Service](https://shorebird.dev/terms) and can end your account. Code Push services such as [Expo](https://expo.dev) are widely used in the industry. ### Does Shorebird comply with App Store guidelines? Yes. Section 3.3.1(B) of the [Apple Developer Program License Agreement](https://developer.apple.com/support/terms/apple-developer-program-license-agreement/#b331) says: > Interpreted code may be downloaded to an Application but only so long as such code: (a) does not change the primary purpose of the Application by providing features or functionality that are inconsistent with the intended and advertised purpose of the Application (b) does not bypass signing, sandbox, or other security features of the OS; and (c) for Applications distributed on the App Store, does not create a store or storefront for other Applications. On iOS, Shorebird runs a patch’s changed code in an interpreter. As long as your updates don’t change the app’s purpose, updating with Shorebird complies with Apple’s guidelines. Deliberately using Shorebird to break them violates Shorebird’s [Terms of Service](https://shorebird.dev/terms) and can end your account. ### Now that you’re using Shorebird, do you still need to send your app to the stores? Yes. New users install from the stores, so periodic store releases give them recent code on first launch. Stores also expect major new features to go through their review. ### Does Shorebird submit to the stores for me? No. `shorebird release` builds your app and uploads a copy to Shorebird. You then submit the `.aab` or `.ipa` to Google Play or App Store Connect yourself, the way you do today. Once users install it, Shorebird can patch it. See [Create a Release](/code-push/release/). ## Use cases & limitations ### What can you use Shorebird Code Push for? Shipping urgent fixes without waiting for a store release, fixing users on older versions of your app, and shipping Dart changes continuously, such as daily or on every commit to `main`. Most app stores prohibit changing an app’s behavior significantly through updates; see [Store compliance](#store-compliance). ### What can’t Shorebird Code Push be used for? Changes to native code (Java or Kotlin on Android, Objective-C or Swift on iOS), assets and the Flutter version: these need a new store release. `shorebird patch` warns when it finds native code or asset changes. Shorebird also shouldn’t be used to break app store policies; see [Store compliance](#store-compliance). ### How does Shorebird check for native code or asset changes? `shorebird patch` compares the patch’s native code and assets with the release. If they differ, it shows what changed and asks `Continue anyway?`, or stops in CI. See [native changes](/code-push/troubleshooting/#your-app-contains-native-changes-warning-when-creating-a-patch-even-though-you-havent-changed-swiftobjective-ckotlinjava-code) and [asset changes](/code-push/troubleshooting/#your-app-contains-asset-changes-warning-when-creating-a-patch) in Troubleshooting. ### Is there a limit to how many patches I can ship per release? No. Each patch gets the next patch number, and only the newest patch is active. Devices download it on their next launch and run it from the launch after that; see [When do updates happen?](#when-do-updates-happen) Publishing a new store release from time to time still helps, because new users install from the store. ### Can you restore a deleted app, release, or patch? No. Deleting an app, a release, or a patch is permanent, and Shorebird support can’t restore it. To stop serving a bad patch, [roll it back](/code-push/rollback) instead, which you can undo. If you’ve already deleted something, see [If you deleted an app or release by mistake](/code-push/delete/#if-you-deleted-an-app-or-release-by-mistake). ### Is Shorebird suitable for enterprise or production apps? Yes. See [Shorebird Success Stories](https://shorebird.dev/success-stories) for examples, and the [Enterprise plan](/enterprise/) for security, compliance, and procurement features. ### Can Shorebird be used for all Dart changes? Yes, any Dart code, including pure Dart packages, as long as the change follows your store’s guidelines (see [Store compliance](#store-compliance)). Each patch is a diff against the release, not against the previous patch, so its size grows with how much Dart code changed since the release. ### Can new packages or plugins be added in a patch? Pure Dart packages, yes. A package with native code (its `pubspec.yaml` has a `flutter: plugin:` section), only if the release already included it. Otherwise its native half isn’t in the store build, so the app crashes or fails when the patch calls it. Add new native packages in a store release. See [Plugins and native code](/flutter-concepts/plugins-and-native-code/). ### How does this relate to Firebase Remote Config or Launch Darkly? They change your app’s configuration without a new version. Code Push changes your app’s code. ### How does this relate to Flutter Hot Reload? Hot reload is for development: it needs a debug build with a just-in-time compiler (see [How Flutter builds your app](/flutter-concepts/how-flutter-builds-your-app/#debug-profile-and-release-builds)). Code Push updates release builds in production. See [How Shorebird Code Push works](/code-push/system-architecture/#how-shorebird-code-push-works). ### Does Shorebird support Swift Package Manager? For a Flutter app, yes. `shorebird release ios` runs `flutter build ipa` with Shorebird’s fork of Flutter, so your app’s iOS plugins are integrated the same way Flutter integrates them, whether through Swift Package Manager or CocoaPods. One difference when patching: the only native change `shorebird patch ios` can warn about is a changed `ios/Podfile.lock`, so it doesn’t warn when your Swift Package Manager dependencies change, or at all if your app has no `Podfile.lock`. Check native changes yourself before patching; see [native changes](/code-push/troubleshooting/#your-app-contains-native-changes-warning-when-creating-a-patch-even-though-you-havent-changed-swiftobjective-ckotlinjava-code). For [add-to-app on iOS](/code-push/guides/add-to-app/ios/), Shorebird supports only embedding the module as `.xcframework` files, not Flutter’s Swift Package Manager integration. ### Does Shorebird support Flutter Web? Code Push isn’t needed for Flutter web: a web app loads the latest version from your server. If you have a use case for it, [let the Shorebird team know](mailto:contact@shorebird.dev). ## Technical details ### What does the Shorebird updater store on disk? The updater keeps its state, including the [anonymous install identifier](#what-is-the-anonymous-install-identifier), and the patches it downloads in your app’s own storage: on Android under `/data/user/0//code_cache/shorebird_updater` (the system chooses the base of that path), and on iOS under `Library/Application Support/shorebird`. An installed patch takes about as much space as your app’s compiled Dart code. The updater deletes patches it no longer needs. ### What do the Shorebird tools store on disk? The `shorebird` CLI lives in `$HOME/.shorebird`, with a copy of Flutter for each Flutter version you’ve built with, in `$HOME/.shorebird/bin/cache/`. Each copy can be hundreds of megabytes. Shorebird 1.6.126 and newer remove Flutter versions, engine artifacts and previews you haven’t used in 30 days. Run `shorebird cache clean --unused` to do that now, or `shorebird cache clean` to clear the whole cache. See [Uninstall](/code-push/uninstall) to remove Shorebird. ### How big of a dependency footprint does this add? Shorebird’s engine includes the updater, so it’s larger than stock Flutter’s. This table compares the two engines for Flutter 3.41.7 (April 2026), measured on the stripped binaries that ship to users: | Platform | Shorebird (on-disk / download) | Flutter (on-disk / download) | Shorebird overhead | | ------------------- | ------------------------------ | ---------------------------- | ------------------- | | iOS (arm64) | 13.25 MB / 5.68 MB | 8.58 MB / 3.67 MB | +4.67 MB / +2.01 MB | | Android (arm64-v8a) | 13.38 MB / 6.40 MB | 10.79 MB / 5.06 MB | +2.58 MB / +1.35 MB | “On-disk” is the size installed on the device. “Download” is the gzipped size, a close proxy for the compressed APK or IPA. Progress on reducing it is tracked in [shorebird#3715](https://github.com/shorebirdtech/shorebird/issues/3715). To measure your own app, copy aside the APK from `flutter build apk --release`, then run `shorebird release android --artifact apk --dry-run --flutter-version=` with the same Flutter version, and compare the two `build/app/outputs/flutter-apk/app-release.apk` files. `--dry-run` builds without creating a release. If that version already has an Android release, the command ends with “It looks like you have an existing android release”, but the APK is already built. ### How do you build a smaller APK for a single Android architecture? Pass `--target-platform` to `shorebird release android`. See [Build a smaller APK for one architecture](/code-push/release/#build-a-smaller-apk-for-one-architecture). ### When do updates happen? By default, the updater checks for a patch when your app starts, on a background thread that doesn’t block the UI. A new patch downloads while the app runs and is applied the next time the app’s process starts. With [package:shorebird\_code\_push](https://pub.dev/packages/shorebird_code_push) you can check at other times, for example after a push notification. See [Update Strategies](/code-push/update-strategies). ### How do you use Shorebird with a long-running Android background process? A patch is applied when the process starts. A foreground service keeps the process alive after the user swipes the app away, so the app keeps running the previous code. To apply patches: 1. Check for and download patches with [package:shorebird\_code\_push](https://pub.dev/packages/shorebird_code_push) while the process runs; automatic updates only run on process start. 2. When `checkForUpdate()` returns `UpdateStatus.restartRequired`, a patch is waiting. Prompt the user to restart when it suits your app. 3. Restart the process: stop the foreground service and swipe the app away, or wait until the OS kills it. While testing, use **Settings → Apps → Force stop**. Recreating the Flutter engine without killing the process doesn’t apply a patch. See [Update Strategies](/code-push/update-strategies). ### What information is sent to Shorebird servers? Only what’s needed to deliver patches and count active installs, and no personally identifiable information. A patch check sends the app ID, the track, the release version, the current patch number, the platform and CPU architecture, and the [anonymous install identifier](#what-is-the-anonymous-install-identifier). Patch events, sent when a patch downloads, installs or fails, add the patch number, a timestamp and, for failures, a short error. Including Shorebird shouldn’t change your Play Store or App Store privacy declarations. [What Shorebird Collects](/system/what-shorebird-collects/) lists every field, with links to the [updater’s source](https://github.com/shorebirdtech/updater). ### Do you need to keep your app\_id secret? No. The `app_id` is safe to make public, including in a public repository. Someone with it can download your app’s patches, but can’t publish patches or access your Shorebird account. ### Does Code Push require the internet to work? Yes. Devices need a network connection to get patches. ### How is Shorebird affected by lack of network connectivity? Your app works as usual. The updater checks for patches on a background thread, and if the request fails or times out, it tries again on the next launch. The `shorebird` CLI needs network access, including in CI. ### What happens if a user doesn’t update for a long time? They get the newest patch for their release version, whichever patch they have now. Each patch contains all your code at the time it was built, so users never miss a fix from an earlier patch. ## Teams, access, and privacy ### Can you use Shorebird with your team? Yes. Your first organization is free, but adding members to it needs a paid plan. See [Organizations](/account/orgs). ### Can you self-host Shorebird? No. Shorebird has no plans to offer on-premises or self-hosted versions. Tell the Shorebird team what you need from the hosted service. ### Does Code Push work with large applications? Yes. There is no limit on the size of app Shorebird can patch, and a patch can change any Dart code in it. ### Does Shorebird store your source code? No. `shorebird release` and `shorebird patch` upload only the compiled app, the same binary you send to the stores. ### What is the anonymous install identifier? A random ID (a v4 UUID) the updater creates the first time your app runs and stores in your app’s own storage, so Shorebird can count how many installs of your app are active. It identifies one install of your app, not a device or a person: two Shorebird apps on one phone get unrelated IDs, and it isn’t derived from anything on the device. It survives release and patch updates, and a new one is created after the app is uninstalled or its data is cleared. In Shorebird’s source code it’s `client_id`; the [privacy policy](https://shorebird.dev/privacy/) calls it an anonymous device identifier. Your bill isn’t based on it: plans are priced on [patch installs](/account/billing/#how-shorebird-bills). See [What Shorebird Collects](/system/what-shorebird-collects/#the-anonymous-install-identifier). ### What does Shorebird do with the anonymous install identifier? Shorebird counts with it, and nothing else. Daily and monthly active install counts are computed as HyperLogLog sketches, aggregates that don’t contain the identifiers, and those counts are what the [Shorebird console](https://console.shorebird.dev) shows you. The identifier is never shown to you or anyone else, no API returns it, it’s never joined with your account data or any other data set, and it’s never sold or shared for advertising. Retention is covered by Shorebird’s [privacy policy](https://shorebird.dev/privacy/). For these commitments as a signed agreement, Shorebird offers a [Data Processing Agreement](https://shorebird.dev/dpa/). For a security review or questionnaire, email . The code that creates and sends the identifier is public: `generate_client_id` in [`updater_state.rs`](https://github.com/shorebirdtech/updater/blob/main/library/src/cache/updater_state.rs) and `PatchCheckRequest` in [`network.rs`](https://github.com/shorebirdtech/updater/blob/main/library/src/network.rs). ### Will your app still work if you cancel your Shorebird subscription? Yes. Apps built with Shorebird keep working, including ones with a patch installed. ### Can you use Shorebird in your country? Shorebird doesn’t restrict access by country, but some countries block hosts. Your users’ devices must reach `https://api.shorebird.dev` (patch checks) and `https://cdn.shorebird.cloud` (patch downloads); without them, the app keeps running its current code but gets no new patches. Your build machines need more hosts, and some can come from an internal mirror. See [Firewalls, proxies and mirrors](/system/firewalls-and-mirrors/), and test your network with [Endpoint Reachability](/system/endpoint-reachability/). ### Do you need to distribute your app through a store? No. Shorebird works with any way of distributing your app, including side-loading. Users install a release some other way, and Shorebird patches it. See [Distribute an APK outside Google Play](/code-push/release/#distribute-an-apk-outside-google-play). ### How does Shorebird interact with Play testing tracks or Apple TestFlight? Shorebird can’t tell which store testing track or TestFlight group a device is in, so it can’t target patches to them. To patch a group separately, use a separate app (for example a flavor) for that group, or use Shorebird’s own [tracks](/code-push/tracks/) to send a patch to devices that opt in. ## Billing ### What counts as a “patch install” for Shorebird? See [How Shorebird Bills](/account/billing/#how-shorebird-bills). ### How do you upgrade or downgrade your plan? From the [Plan page](https://console.shorebird.dev/account/plan) in the Shorebird Console. Upgrades take effect immediately; downgrades at the end of the billing period. See [Plans & Upgrading](/account/plans/). ### When does your billing period reset? A paid plan’s period starts on the day checkout completes and renews on that date each month, or each year on an annual plan. On the free Hobby plan, it’s the calendar month (UTC). See [Overage billing](/account/billing/#overage-billing) and [Switch between monthly and annual billing](/account/plans/#switch-between-monthly-and-annual-billing). ### How do you cancel your subscription? Click “Cancel plan” on the [Plan page](https://console.shorebird.dev/account/plan). Your paid features last until the end of the billing period. See [Cancel your plan](/account/plans/#cancel-your-plan). ### Can you pay for a year in advance? Yes, with annual billing. See [Switch between monthly and annual billing](/account/plans/#switch-between-monthly-and-annual-billing).