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).
• Match Flutter Versions: Ensure your local Flutter SDK version is identical to the one vended by Shorebird. You can check this by running shorebird doctor.

Android

Android

shorebird patch android

iOS

iOS

shorebird patch ios

Linux

Linux

shorebird patch linux

macOS

macOS

shorebird patch macos

Windows

Windows

shorebird patch windows

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

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

This will do several things:

1. Builds the artifacts for the update.
2. Downloads the corresponding release artifacts.
3. Generates a patch using the diff between the release and the current changes.
4. Uploads the patch artifacts to the Shorebird backend.
5. Promotes the patch to the stable channel.

Example output:

$ shorebird patch android
✓ Building patch (3.0s)
✓ Fetching apps (0.2s)
✓ Detecting release version (0.3s)
✓ Fetching release (77ms)
✓ Fetching Flutter revision (15ms)
✓ Fetching release artifacts (0.3s)
✓ Downloading release artifacts (1.9s)
✓ Creating artifacts (4.1s)

🚀 Ready to publish a new patch!

📱 App: My App (61fc9c16)
📦 Release Version: 0.1.0+1
📺 Channel: stable
🕹️  Platform: android [arm64 (166.20 KB), arm32 (161.78 KB), x86_64 (161.51 KB)]

Would you like to continue? (y/N) Yes
✓ Creating patch (93ms)
✓ Uploading artifacts (1.5s)
✓ Fetching channels (86ms)
✓ Promoting patch to stable (78ms)

✅ Published Patch!

By default, this uses the release version from the compiled artifact. If you want to target the latest release version, you can use --release-version latest. For example:

shorebird patch android --release-version latest

If you want to patch a different release version, you can use the --release-version option. For example:

shorebird patch android --release-version 0.1.0+1

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

Note

shorebird patch wraps flutter build and can take any argument flutter build can. To pass arguments to the underlying flutter build, you need to put flutter build arguments after a -- separator. For example: shorebird patch android -- --dart-define="foo=bar" will define the "foo" environment variable inside Dart as you might have done with flutter build directly.

Options

Option	Abbreviation	Description
--release-version		The release version to patch (e.g., 1.0.0+1). Use latest to target the most recently updated release.
--platforms	-p	Comma-separated list of platforms to patch simultaneously (e.g., android,ios).
--flavor		The product flavor to use when building.
--target	-t	The main entrypoint file of the application.
--track		The deployment track to publish to (default: stable). Use staging to publish to a staging track first.
--dry-run	-n	Build and validate the patch but do not upload it. Ideal as a CI sanity check.
--allow-asset-diffs		Publish even if asset differences are detected. Not recommended.
--allow-native-diffs		Publish even if native code differences are detected. Not recommended.

iOS-specific Options

Option	Description
--no-codesign	Skip code signing for the iOS build.
--export-options-plist	Path to a custom ExportOptions.plist for the iOS archive export step.
--export-method	Distribution method: app-store, ad-hoc, development, or enterprise.
--min-link-percentage	Minimum % of Dart code that must be linked (not interpreted) for the patch to publish. iOS only.

Patch Performance

Android

Patching an application on Android has no effect on performance.

iOS and macOS

Patching an application on iOS and macOS typically does not affect application performance. However, the patching mechanism on iOS and macOS is different from Android. 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 and macOS patching works, see System Architecture.

If you ever see unexpected performance changes when patching, please contact us, and we would love to 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 metadata for the specified patch, including build logs, checksums, and deployment track information.

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

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