---
title: "Create a Patch"
description: "Learn how to push updates to an app with Shorebird."
---

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

**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](mailto:contact@shorebird.dev) for help.

* 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

[Section titled “Patching multiple platforms simultaneously”](#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!
```

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?](/code-push/faq#is-there-a-limit-to-how-many-patches-i-can-ship-per-release) for more details.

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

[Section titled “Options”](#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. See [Tracks](/code-push/tracks) for more. |
| `--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

[Section titled “iOS-specific options”](#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

[Section titled “Patch performance”](#patch-performance)

#### Android

[Section titled “Android”](#android)

Patching an application on Android has no effect on performance.

#### iOS and macOS

[Section titled “iOS and macOS”](#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](/code-push/guides/staging-patches). For a detailed look at how iOS and macOS patching works, see [System Architecture](/code-push/system-architecture).

If you ever see unexpected performance changes when patching, please [reach out](mailto:contact@shorebird.dev) for help.

***

## Manage patches

[Section titled “Manage patches”](#manage-patches)

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

### List patches

[Section titled “List patches”](#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

[Section titled “View patch details”](#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

[Section titled “Promote a patch”](#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

[Section titled “Set patch track”](#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
```