How do you temporarily switch a Flutter app off Impeller to check a rendering bug, and why is that only a short-term measure?

## Why you would switch renderers at all When a Flutter screen draws something wrong (a missing blur, a clip with jagged edges, a gradient with banding, a custom shader that looks different) the first question is whether it is **your code** or **the renderer**. If the same build looks correct with the legacy renderer and wrong with Impeller, you have an Impeller-specific issue to report, and a candidate workaround while it is fixed. If it looks wrong with both, the bug is in your drawing code. ## How to switch, per platform | Platform | During development | In a built app | |---|---|---| | iOS | not possible | not possible: Impeller is the only renderer | | Android | `flutter run --no-enable-impeller` | `io.flutter.embedding.android.EnableImpeller` = `false` in `AndroidManifest.xml` | | macOS | `flutter run --no-enable-impeller` | `FLTEnableImpeller` = `false` in `Info.plist` | | Linux | `flutter run --no-enable-impeller` | `fl_dart_project_set_enable_impeller(project, FALSE)` in `linux/runner/my_application.cc` | | Windows | `flutter run --no-enable-impeller` | `project.set_impeller_switch(flutter::ImpellerSwitch::Disabled)` in `windows/runner/main.cpp` | `--no-enable-impeller` is the negated form of the `flutter` tool's boolean `--enable-impeller` flag. Note that the flag's own help text, shown only with verbose help, still describes an older state in which Android was not Impeller by default; the platform docs are the current reference. ## Checking a backend instead of the renderer On Android, a glitch may be specific to one Impeller **backend**. In debug and profile builds, a manifest entry `io.flutter.embedding.android.ImpellerBackend` with the value `opengles` forces Impeller's OpenGL ES backend instead of Vulkan. That separates "Impeller bug" from "Vulkan driver bug" without leaving Impeller. It does nothing in release builds. ## Why it is only a short-term measure 1. **It brings back the problem Impeller solved.** The legacy renderer compiles shaders at runtime, so disabling Impeller reintroduces first-run animation jank for every user of that build. 2. **It will stop working.** The docs state that on macOS, Windows and Linux the ability to opt out will be removed in a future release, and the Android docs warn the same. iOS already removed it. 3. **It splits your test matrix.** A build with Impeller disabled behaves differently from the default everyone else ships, so fixes and performance numbers do not transfer. 4. **It hides the bug from the people who can fix it.** The renderer only improves if issues are reported. ## What to do with the result If the glitch disappears with the legacy renderer: - Build the **smallest reproducible case**: one widget, one effect. - **File an issue** on the Flutter tracker with the title prefixed `[Impeller]`, the device and chip, screenshots or a recording, and an exported performance trace, as the Impeller docs ask. - Look for a **workaround in your code**, such as a different way of drawing the same effect, rather than shipping the opt-out. - If you truly must ship the opt-out for one platform, record why, link the issue, and schedule its removal. ## A worked example A Windows build of an app shows a card whose rounded clip has jagged edges after upgrading to 3.47: 1. Run `flutter run --no-enable-impeller` on the same machine. The edges are smooth, so the difference is renderer-specific. 2. Reduce the screen to one `ClipRRect` around a coloured box and confirm the difference still reproduces. 3. File the issue with an `[Impeller]` title prefix, the GPU model, screenshots of both renderers and a performance trace export. 4. Meanwhile, try drawing the same shape another way in your own code (for example a decorated container with a border radius instead of a clip) and keep Impeller on. 5. Only if no workaround exists, ship the Windows opt-out with a comment linking the issue, and remove it when the fix lands. ## A note on desktop Impeller only became the default on macOS, Windows and Linux in 3.47, so desktop apps are the likeliest to meet a new Impeller difference right now. The same rules apply: switch to confirm, report, work around in code, and do not rely on the opt-out lasting.