FAQ

Still have a question about Patchwing Code Push that our docs didn’t cover? You’re in the right place. This page covers the most common questions. If you have a question not answered here or elsewhere in the docs, reach out via email. We’re here to help.

Getting Started

What is the difference between a patch and a release?

We use the term “release” to mean preparing a binary for the app stores. In order to later generate a patch Patchwing needs to know the exact binary that was shipped to the app stores. The patchwing release command is used to prepare a binary for the app stores which includes the Patchwing updater.

We use the term “patch” to mean a binary that can be applied to a release to update it to new code. The patchwing patch command is used to generate a patch from your new local code which is then diffed with the release binary to generate a patch which is then shipped to your users.

We explain more of these terms in Overview.

When should I create a patch vs a release?

Because patching and releasing are independent operations, it is possible to create both a patch and a release with the same code changes.

Different customers have used different policies to decide whether to create a release, a patch, or both. Some of these polices include:

Push a patch immediately to update all existing users, while also simultaneously submitting a release to the stores so that new users to their product will get the latest code on first launch after a store install.
Use patching as a mechanism to ship changes on a high frequency (e.g. daily or weekly) and only go through a full release process on a lower cadence (e.g. monthly).
Continue to only use releases for shipping code changes, and only patch to fix critical bugs or make other emergency changes.

In the end, it comes down to what works for your business. We see most of our current customers choosing option 2.

Can I use Patchwing from my CI system?

Yes. Create an API key in the Patchwing Console under Account → API Keys, then add it to your CI environment as PATCHWING_TOKEN. See our CI setup guide for detailed instructions.

Can I use Dart defines with Patchwing?

Yes. The patchwing command line tool passes through all Dart defines to the flutter tool. For example, patchwing release android -- --dart-define=MY_DEFINE=foo and patchwing release android -- --dart-define-from-file=config.json will both work as expected. Because Dart defines are compiled into your app’s Dart code, they can be updated via patches.

How does Patchwing relate to Flutter?

Patchwing is a fork of Flutter that adds code push. Patchwing is not a replacement for Flutter, but rather a replacement for the Flutter engine. You can continue to use the Flutter tooling you already know and love.

patchwing uses a fork of Flutter that includes the Patchwing updater. We track the latest stable release of Flutter and replace a few of the Flutter engine files with our modified copies.

To implement our fork, we use FLUTTER_STORAGE_BASE_URL to point to https://download.patchwing.net instead of download.flutter.dev. We pass through unmodified output from the flutter tool so you will see a warning from Flutter:

Flutter assets will be downloaded from http://download.patchwing.net. Make sure you trust this source!

For more information about why we had to fork Flutter see System Architecture.

What platforms does Patchwing support?

Patchwing supports Android, iOS , Mac, Windows, and Linux.

Use of Patchwing on each platform is an independent decision. For example You can use patchwing release to ship to Google Play and an ipa built with flutter build to the App Store or vice versa.

What OS versions does Patchwing support?

Patchwing supports the same versions of platforms that Flutter supports. You can find the details of this on the Flutter Docs site.

What versions of Flutter does Patchwing support?

For specific versions by platform please consult out Flutter Version Management page.

Patchwing tracks Flutter stable and generally updates within a few hours of any stable release. Our system for doing these updates is automated. We then do an extra manual verification step before publishing to our servers.

Store Compliance

Does Patchwing comply with Play Store guidelines?

Yes.

The Play Store offers two restrictions relating to update tools.

Updates must use an interpreter or virtual machine (Patchwing uses the Dart Virtual Machine). https://support.google.com/googleplay/android-developer/answer/9888379?hl=en

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

    Apps or third-party code, like SDKs, with interpreted languages (JavaScript,
    Python, Lua, etc.) loaded at run time (for example, not packaged with the
    app) must not allow potential violations of Google Play policies.

Changes to the app must not be deceptive (e.g. changing the purpose of the app via update). https://support.google.com/googleplay/android-developer/answer/9888077 Please be clear with your users about what you are providing with your application and do not violate their expectations with significant behavioral changes through the use of Patchwing.

Patchwing is designed to be compatible with the Play Store guidelines. However Patchwing is a tool, and as with any tool, can be abused. Deliberately abusing Patchwing to violate Play Store guidelines is in violation of the Patchwing Terms of Service and can result in termination of your account.

Code push services are widely used in the industry (all of the large apps I’m aware of use them) and there are multiple other code push services publicly available (e.g. expo.dev & appcenter.ms). This is a well trodden path.

Microsoft also publishes a guide on how their React Native “codepush” library complies with the app stores: https://github.com/microsoft/react-native-code-push#store-guideline-compliance

Does Patchwing comply with App Store guidelines?

Yes.

Similar to the Play Store, the App Store offers both technical and policy restrictions.

3.3.1b
... 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 as submitted to the App Store,
(b) does not create a store or storefront for other code or applications, and
(c) does not bypass signing, sandbox, or other security features of the OS.

Patchwing uses a custom Dart interpreter to comply with the interpreter-only restriction for updates on iOS. So long as your application is not engaging in deceptive behavior via updates (e.g. changing the purpose of the app via update), updating via Patchwing (or any other code push solution) is standard industry practice and compliant with App Store guidelines.

Deliberately abusing Patchwing to violate App Store guidelines is in violation of the Patchwing Terms of Service and can result in termination of your account.

Microsoft also publishes a guide on how their react native “codepush” library complies with the app stores: https://github.com/microsoft/react-native-code-push#store-guideline-compliance

Now that I’m using Patchwing, do I still need to send my app to the stores?

Yes. We recommend customers continue to release their app through the stores in addition to using Patchwing. Even if this now means that there can be less pressure on your app release process.

This is for two reasons:

Stores have policy restrictions that “major new features” go through store review to avoid “deceiving users”. Since apps are likely to change over time, periodic releases (to update store screenshots, etc.) is still good practice.
New users install from the stores, not Patchwing. Patchwing can only update your application after launch, so for users to get the best first-launch experience, we recommend that you continue to periodic releases to the stores.

Does Patchwing submit to the stores for me?

Patchwing does not currently support submitting to the app stores on your behalf. We may end up adding this in the future, but for now you will need to continue to use your existing processes to submit to the app stores.

Use Cases & Limitations

What can I use Patchwing code push for?

We’ve seen a variety of uses, including:

Emergency fixes to production apps.
Shipping bug fixes to users on older versions of your app.
Shipping constantly (e.g. daily, every commit to main, etc).

Note that most app stores prohibit shipping code that changes the behavior of the app in a significant way. Please see our Store Compliance section for more information.

What can’t we use Patchwing code push for?

Patchwing does not support changing native code (e.g. Java/Kotlin on Android or Objective-C/Swift on iOS). The tool will warn you during an attempted patch if you have changed native code.

Patchwing should not be used to violate app store polices. Please see our Store Compliance section for more information.

Can I use Patchwing for all my Dart changes?

Patchwing can be used to update any Dart code including pure Dart packages. Note that depending on how you distribute your apps, some store agreements expect feature changes to go through store review. Notably Apple’s App Store requires that an update “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.” Also note that patch sizes correlate with the total amount of Dart changed from the original released app. Each patch is a diff against the released dart code, not a diff to the previous patch.

How does this relate to Firebase Remote Config or Launch Darkly?

Code push allows adding new code / replacing code on the device. Firebase Remote Config and Launch Darkly are both configuration systems. They allow you to change the configuration of your app without having to ship a new version. They are not intended to replace code.

How does this relate to Flutter Hot Reload?

Flutter’s Hot reload is a development-time-only feature. Code push is for production.

Hot reload is a feature of Flutter that allows you to change code on the device during development. It requires building the Flutter engine with a debug-mode Dart VM which includes a just-in-time (JIT) Dart compiler.

Code push is a feature that allows you to change code on the device in production. We will use a variety of different techniques to make this possible depending on the platform. Current demos execute ahead-of-time compiled Dart code and do not require a JIT Dart compiler.

Does Patchwing support Flutter Web?

Code push isn’t needed for Flutter web. When a user opens a web app it downloads the latest version from the server if needed.

If you have a use case for code push with Fluter web, we’d love to know!

Technical Details

What does the Patchwing updater store on disk?

The Patchwing updater (included in your application when you build your app with Patchwing) caches the latest downloaded patch in the same cache directory that Flutter uses for caching compiled shaders or compiled Dart code. On Android, this is located in /data/user/0/com.example.app/code_cache/patchwing_updater although the base of that path is provided by the Android system and can change dynamically at runtime. On iOS devices, data is stored under Library/Application Support/patchwing.

Patchwing stores only a few files, one is state.json which contains the state information for the updater. When a patch is downloaded a directory will be created for that patch. These directories contain the inflated copies of the patches, which will be about the same size as the compiled Dart code in your application (e.g. ~10 mb each). There will only be at most 2 patches downloaded on the device at a given time. When a new patch is successfully installed and launched, the previous patch is deleted.

What do the Patchwing tools store on disk?

The Patchwing command line tools (e.g. patchwing patch) are installed on disk in $HOME/.patchwing, including bringing a copy of Flutter and Dart as well as the Patchwing release tools themselves. This is similar to how the flutter command works.

These copies of Flutter can be 100s of megabytes each. Patchwing will keep a copy of Flutter $HOME/.patchwing/bin/cache/ for each version of Flutter you have used. Currently this number is unbounded. These can be removed at any time with patchwing cache clear.

Uninstall has details on how to remove Patchwing from your system should you choose.

How big of a dependency footprint does this add?

Patchwing ships its own build of the Flutter engine with the patching runtime included, which is where the overhead comes from. The table below compares Patchwing’s engine against stock Flutter for the same engine version, measured on the stripped binaries that actually ship to users:

Platform	Patchwing (on-disk / download)	Flutter (on-disk / download)	Patchwing 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 uncompressed size installed on the device. “Download” is the approximate size shipped over the store — APKs and IPAs use DEFLATE compression, which gzip -9 closely mimics, so the gzipped size is a good proxy for what a user’s device actually pulls down.

These numbers are for Flutter 3.41.7 (April 2026). Earlier Patchwing engines were meaningfully larger — iOS overhead alone came down by roughly 2 MB on-disk in the preceding month — and we continue to shrink the overhead; progress is tracked in patchwing#3715. You can reproduce a rough measurement on your own app by comparing the output of flutter build apk --release against patchwing build apk --release.

When do updates happen?

By default, the Patchwing updater checks for updates on app startup. It runs on a background thread and does not block the UI thread. Any updates will be installed while the user is using the app and will be applied the next time the app is restarted.

It is also possible to run the Patchwing updater manually using package:patchwing_code_push, through which it is possible to trigger updates at any time, including via a push notification.

See Update Strategies for more information about how to configure this behavior.

What information is sent to Patchwing servers?

Although Patchwing connects to the network, it does not send any personally identifiable information (PII). Including Patchwing should not affect your declarations for the Play Store or App Store.

Requests sent from the app to Patchwing servers include:

app_id (specified patchwing.yaml)
channel (optional in patchwing.yaml)
release_version (versionName from AndroidManifest.xml)
patch_number (generated as part of patchwing patch android)
arch (e.g. ‘aarch64’, needed to send down the right patch)
platform (e.g. ‘android’, needed to send down the right patch)
client_id (anonymous, aggregated, per-app identifier used to provide active user metrics)

The code for this is public in our updater package and can be reviewed at any time.

Do I need to keep my app_id secret?

No. The app_id is included in your app and is safe to be public. You can check it into version control (even publicly) and not worry about someone else accessing it.

Someone who has your app_id can fetch the latest version of your app from Patchwing servers, but they cannot push updates to your app or access any other aspect of your Patchwing account.

Does code push require the internet to work?

Yes. Some form of network connectivity is required to transport updates to the devices.

How is Patchwing affected by lack of network connectivity?

The Patchwing updater is designed to be resilient to network connectivity issues.

In the default update behavior, when the application launches it alerts the Patchwing updater, which spawns a separate thread to make a network request to Patchwing’s servers and ask for an update. We intentionally use a separate thread to avoid affecting blocking anything else the application might be doing. If the network request fails or times out, the updater will simply try to check again next time the application launches.

Patchwing command line tools (e.g. patchwing patch) require network connectivity to function. If you are using Patchwing to distribute your app, you should ensure that your CI system has network connectivity.

What happens if a user doesn’t update for a long time?

A user will always get the latest patch available for their version of the app, regardless of which patch (if any) they currently have installed. A patch will always reflect the state of the codebase at the time when the patch was built so as long as newer patches also contain the changes from older patches, users will always be up to date and there is no need to worry about users “missing” patches.

Teams, Access, and Privacy

Can I use Patchwing with my team?

Yes! The Patchwing free “Hobby” tier only supports a single developer, but all other plans support unlimited developers.

See Organizations for more information.

Can I self-host Patchwing?

No. Patchwing has no current plans to offer on-prem, self-host or cloud-prem offerings. We would be happy to discuss with you any and all ways in which we can improve our centrally hosted solution to best match your needs.

Does code push work with large applications?

Yes. There is no limit on the size of the application that can be patched with code push. As noted in Overview, Patchwing can change any Dart code in your application no matter of size.

Does Patchwing store my source code?

No. Patchwing servers never see or store your source code. When you run patchwing release or patchwing patch the patchwing tool only uploads the same compiled app binary that you send to the app stores.

Will my app still work if I cancel my Patchwing subscription?

Yes. Apps built with Patchwing will continue to function normally (as if they had been built without Patchwing), including those that have had patches installed.

Can I use Patchwing in my country?

We have not attempted to restrict access to Patchwing from any country.

We recognize that some countries have restrictions on what urls can be accessed from within the country. Patchwing currently uses Google Cloud for hosting, including Google Cloud Storage and Google Cloud Run.

The following URLs are used by Patchwing:

https://console.patchwing.net — used to interact with Patchwing’s services via the web.
https://auth.patchwing.net — used to authenticate with Patchwing
https://api.patchwing.net — used by the patchwing command line tools to interact with the Patchwing servers as well as the Patchwing updater on users’ devices to check for updates.
https://download.patchwing.net — used by the patchwing command line tool to download Flutter artifacts for building releases and patches.
https://storage.googleapis.com — used by the patchwing command line tool to upload and download release and patch artifacts, and by the Patchwing updater on user’s devices to download the patches.
https://cdn.patchwing.net/ — used by the Patchwing updater when downloading patches to a user’s device.

Patchwing also uses Microsoft or Google OAuth login, which have their own required urls for login (e.g. login.microsoftonline.com or oauth.google.com).

All traffic to and from Patchwing servers travels over https (port 443) and is encrypted using standard Transport Security Layer / Secure Sockets Layer (TSL/SSL) protocols.

If all of those URLs are accessible from your country, then Patchwing should work.

If your region requires use of FLUTTER_STORAGE_BASE_URL Patchwing may not work for you at this time as we also use that environment variable as part of our implementation. We have plans to remove this restriction in the future.

Do I need to distribute my app through a store?

No. Patchwing can be used with any app distribution method, including side-loading or carrier provided stores.

Patchwing is not itself a store. Your users will need to install your app initially through some method other than Patchwing, but Patchwing can then be used to patch (update) your app after that initial install.

How does Patchwing interact with Play Testing Tracks or Apple TestFlight?

Each of the app stores have separate mechanisms for distributing apps to limited groups of users (e.g. “internal testing”, “closed beta”, etc.). These are all mechanisms for segmenting your users into groups and distributing specific versions of your apps to each.

Unfortunately, these not all of these mechanisms allow 3rd parties to detect when apps are installed in any specific Test Track or via TestFlight. Thus, we do not have reliable visibility into composition of these groups, and cannot reliably gate access to Patchwing patches based on these groups. You can read a bit more about this on Stack Overflow discussions specifically about Android and iOS.

If you’d like to segment availability of Patchwing patches, there are some potential options:

Use separate binaries / bundle ids for each group. This is the most straightforward approach, but requires you to manage multiple binaries. On Android the easy way to accomplish this is through flavors. You may already have a dev flavor and prod flavor with different availability. You can thus patch your dev flavor, verify it and then separately patch your prod flavor. We recommend using branches / tags in your version control to help keep track of the sources associated with each release.
Track your own set of opt-in users, disable automatic updates, and trigger updates only for certain users via package:patchwing_code_push. This requires you to manage your own opt-in list.

Billing

What counts as a “patch install” for Patchwing?

For more details on this, please refer to the How We Bill section of our Billing page.

How do I upgrade or downgrade my plan?

To upgrade your plan, you can subscribe via the Patchwing console. You would like to move from a monthly to yearly plan please reach out to us via email to complete the change.

When does my billing period reset?

Billing periods are reset automatically every month on the day you first subscribed to Patchwing. For example, if you subscribed on the 15th of the month, your billing period will reset on the 15th of every month.

How do I cancel my subscription?

To cancel your subscription, you can view your account and click “Edit” -> “Cancel Subscription”.

You will continue to have all the features of a paid account until the end of your billing period.

Can I pay for a year in advance?

Yes! We launched support for self-service yearly plans in April 2025. You can read more about this in our announcement blog post.