Create a Patch

Once you have published a release of your app, you can push updates using one of the shorebird patch commands.

Pre-Patch Checklist

Before running a patch command, review this checklist to ensure your patch compiles and applies cleanly:

• No Native Code Changes: Ensure your updates do not touch native platform code (e.g. Kotlin, Swift, or build configurations in android/ or ios/). Native updates cannot be patched.
• No Asset Changes: Check that no new images, fonts, or other files have been added or removed in pubspec.yaml (asset patching is not yet supported).
• Flutter Version: No action needed. shorebird patch builds with the Flutter revision the release used, automatically.

What Shorebird checks automatically: Before creating a patch, Shorebird compares your local build against the stored release artifacts and warns you (or blocks the upload by default) if it detects native code or asset differences. You can bypass these checks with --allow-native-diffs or --allow-asset-diffs. If you find yourself needing these flags, it is likely a Shorebird bug or you may be running an old version of shorebird — please reach out for help.

Android

Android

shorebird patch android --track=stable

iOS

iOS

shorebird patch ios --track=stable

Linux

Linux

shorebird patch linux --track=stable

macOS

macOS

shorebird patch macos --track=stable

Windows

Windows

shorebird patch windows --track=stable

Patching multiple platforms simultaneously

If your app supports multiple platforms, you can build and publish patches for them in a single command using the --platforms (or -p) option:

shorebird patch --platforms=android,ios --track=stable

This will build and promote the patches for the specified platforms to their respective releases in one step.

This will do several things:

1. Downloads the corresponding release artifacts.
2. Builds the artifacts for the update.
3. Generates a patch using the diff between the release and the current changes.
4. Uploads the patch artifacts to the Shorebird backend.
5. Publishes the patch to the track you pass with --track or choose when asked. See Tracks.

Example output:

$ shorebird patch android --release-version 0.1.0+1 --track=stable
✓ Fetching app (0.2s)
✓ Fetching releases (0.1s)
✓ Fetching release artifacts (0.3s)
✓ Fetching aab artifact (0.1s)
✓ Fetching android_supplement artifact (0.1s)
✓ Downloading aab (100%) (1.9s)
Building patch with Flutter 3.47.9 (8352242a91)

Running Gradle task 'bundleRelease'...                             41.2s
✓ Built build/app/outputs/bundle/release/app-release.aab (21.4MB)
✓ Verifying patch can be applied to release (0.4s)
✓ Downloading release artifact 1/3 (100%) (0.5s)
✓ Downloading release artifact 2/3 (100%) (0.5s)
✓ Downloading release artifact 3/3 (100%) (0.5s)
✓ Creating patch artifacts (2.1s)

🚀 Ready to publish a new patch!

📱 App: My App (61fc9c16-3c2b-4a6f-9d1e-2f8a7b5c4d3e)
📦 Release Version: 0.1.0+1
🕹️  Platform: Android [arm32 (161.78 KB), arm64 (166.20 KB), x86_64 (161.51 KB)]
🟢 Track: Stable

✓ Creating patch (93ms)
✓ Uploading artifacts (1.5s)
✓ Fetching channels (86ms)
✓ Promoting patch to stable (78ms)

✅ Published Patch 1!

Note

There is no limit on the number of patches you can publish. See Is there a limit to how many patches you can ship? for more details.

Each patch is for one release version. See Release versions for how Shorebird uses your app’s version.

To choose the release, pass --release-version:

shorebird patch android --release-version 0.1.0+1 --track=stable

--release-version latest targets the most recently updated release for that platform:

shorebird patch android --release-version latest --track=stable

Without --release-version, shorebird patch asks you to pick a release when it runs in a terminal. When it can’t ask, as in CI, always pass --release-version. Without it, shorebird patch builds the app first and reads the release version from the build, and can reuse that build as the patch, without the release’s settings, such as obfuscation. An Android archive (aar) or iOS framework for add-to-app has no version to read, so pass the host app’s release version.

In CI, pass the exact version of the release your users have, such as --release-version 1.0.0+1, when you might have a newer release that hasn’t shipped yet. latest targets the most recently updated release, which may be that newer one.

A patch is built with the Flutter version of its release and can’t change it. Shorebird 1.6.135 and newer warn when that version has a known problem on the platform you’re patching, such as the iOS crash in Flutter 3.44.

If your application supports flavors or multiple release targets, you can specify the flavor and target using the --flavor and --target options:

shorebird patch android --target lib/main_development.dart --flavor development --track=stable

Note

shorebird patch wraps flutter build and can take any argument flutter build can. Pass common ones directly, as in shorebird patch android --dart-define="foo=bar" or shorebird patch android --no-tree-shake-icons. Put any other flutter build argument after a -- separator, as in shorebird patch android -- <flutter build arguments>. Shorebird 1.6.136 or older needs the separator for --no-tree-shake-icons too. Use the same arguments the release was built with, so the patch builds the same app.

Options

The options on this page cover most patches: --release-version, --track, --platforms, --flavor and --target. A few others come up often:

• --dry-run (-n) builds and checks the patch without uploading it, which is useful in CI.
• --export-options-plist points an iOS patch at the same ExportOptions.plist as its release.
• --min-link-percentage sets how much of an iOS patch’s Dart code must run natively rather than in the interpreter. Shorebird 1.6.135 and newer default to 20; 0 accepts any patch. See Link percentage and slow patches.
• --allow-native-diffs and --allow-asset-diffs publish a patch even when Shorebird detects native or asset changes. They’re not recommended: a patch can’t change native code or assets.

Run shorebird patch --help for every option.

Patch performance

Android, macOS, Linux and Windows

Patching an application on these platforms has no effect on performance. A patch replaces your app’s compiled Dart code with a newly compiled version, so all of it runs on the CPU as before.

iOS

Patching an application on iOS typically does not affect application performance. However, the patching mechanism on iOS is different from other platforms. Unchanged code runs as normal (on the CPU), changed (or added) code will run in a Dart interpreter (slower than the CPU). Typically this change is undetectable, but if you are changing particularly performance-sensitive Dart code (e.g., code for processing images, or large datasets), you may see a performance difference after patching.

You can always test your patches before sending them to users by staging patches. For a detailed look at how iOS patching works, see System Architecture.

If you ever see unexpected performance changes when patching, please reach out for help.

---

Manage patches

You can manage your patches directly from the command line using the shorebird patches commands.

List patches

To list all patches associated with a specific release version:

shorebird patches list --release-version 1.0.0+1

This will display a list of all patches published for that release, their patch numbers, active status, and tracks.

View patch details

To view detailed information for a specific patch number:

shorebird patches info --release-version 1.0.0+1 --patch-number 1

This command shows the patch’s ID, track, whether it is rolled back, any notes, and the size of each platform and architecture artifact.

Promote a patch

If you published a patch to a staging track (e.g., staging) and verified it works correctly, you can promote it directly to the stable track using:

shorebird patches promote --release-version 1.0.0+1 --patch-number 1

promote is set-track with the track defaulting to stable. Older CLIs run the same command but print a deprecation warning, and its --track, --channel, --app-id, and --json flags need Shorebird 1.6.130 or newer.

Set patch track

To assign a patch directly to a specific deployment track (e.g., promoting or routing to a staging beta group):

shorebird patches set-track --release-version 1.0.0+1 --patch-number 1 --track staging

The --release-version and --patch-number flags of set-track need Shorebird 1.6.128 or newer. On an older CLI, use --release and --patch instead, or run shorebird upgrade first.

Roll back or roll forward a patch

To stop serving a patch, roll it back. To serve it again later, roll it forward:

shorebird patches rollback --release-version 1.0.0+1 --patch-number 1
shorebird patches rollforward --release-version 1.0.0+1 --patch-number 1

See Roll back a Patch for what happens on devices and the options these commands take.

Delete a patch

Individual patches can’t be deleted. A patch is removed along with the release it belongs to, or the app that owns that release. Those deletions are permanent, and the console asks you to confirm before anything is removed.

Tip

To stop serving a patch, use rollback. It remotely uninstalls the patch from end users’ devices, and you can undo it later.

See Delete Apps, Releases, and Patches for details.