FAQ

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. Still have a question? Reach out on Discord or file an issue.

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.

Your account keeps signing in with the method you first used. See 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.

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?

Can you use Shorebird in your CI system?

Yes. Create an API key in the Shorebird Console under Account → API Keys, then add it to your CI environment as SHOREBIRD_TOKEN. See the CI setup guide 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. To test a patch before your users get it, see 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 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 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.

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.

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 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 <version> 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=<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.

Store compliance

Does Shorebird comply with Play Store guidelines?

Yes. Google Play’s Device and Network Abuse policy 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, 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 and can end your account. Code Push services such as Expo 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 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 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.

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.

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.

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 and asset changes 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? 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 instead, which you can undo. If you’ve already deleted something, see If you deleted an app or release by mistake.

Is Shorebird suitable for enterprise or production apps?

Yes. See Shorebird Success Stories for examples, and the Enterprise plan 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). 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.

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). Code Push updates release builds in production. See 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.

For add-to-app on 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.

Technical details

What does the Shorebird updater store on disk?

The updater keeps its state, including the anonymous install identifier, and the patches it downloads in your app’s own storage: on Android under /data/user/0/<package>/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 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.

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=<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.

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 you can check at other times, for example after a push notification. See 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 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.

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. 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 lists every field, with links to the updater’s source.

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.

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 calls it an anonymous device identifier.

Your bill isn’t based on it: plans are priced on patch installs. See What Shorebird Collects.

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 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. For these commitments as a signed agreement, Shorebird offers a Data Processing Agreement. For a security review or questionnaire, email contact@shorebird.dev. The code that creates and sends the identifier is public: generate_client_id in updater_state.rs and PatchCheckRequest in 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, and test your network with 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.

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 to send a patch to devices that opt in.

Billing

What counts as a “patch install” for Shorebird?

See How Shorebird Bills.

How do you upgrade or downgrade your plan?

From the Plan page in the Shorebird Console. Upgrades take effect immediately; downgrades at the end of the billing period. See Plans & Upgrading.

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 and Switch between monthly and annual billing.

How do you cancel your subscription?

Click “Cancel plan” on the Plan page. Your paid features last until the end of the billing period. See Cancel your plan.

Can you pay for a year in advance?

Yes, with annual billing. See Switch between monthly and annual billing.