Installation

Android#

Add-to-app hosts must declare the Kotlin Gradle Plugin themselves. Flutter auto-applies KGP to plugin modules only when the host provides it, so a Java-only native host fails with Could not find method kotlin(). Add KGP to the host's root buildscript/plugins {}. A normal flutter build app needs nothing — Flutter's own Gradle plugin carries KGP.

GPU (any engine): nothing to add. flutter_gemma's own manifest declares the OpenCL namespace entries and the manifest merger folds them into your app. These are what your merged manifest must contain if you pin or audit it — note libvndksupport.so: without it the OpenCL ICD load is denied on Android 12+, the engine falls back to WebGPU, and some Mali drivers hard-freeze (#324).

<uses-native-library android:name="libvndksupport.so" android:required="false"/>
<uses-native-library android:name="libOpenCL.so" android:required="false"/>
<uses-native-library android:name="libOpenCL-car.so" android:required="false"/>
<uses-native-library android:name="libOpenCL-pixel.so" android:required="false"/>

ProGuard/R8 (only if you use flutter_gemma_mediapipe): the package ships its own consumer ProGuard rules; from 1.0.6 a release build needs no rules in your app (built on AGP 9.1). On 1.0.5 and earlier R8 fails the release build with Missing class (seen on AGP 9) — upgrade to 1.0.6, or add to your proguard-rules.pro:

-dontwarn com.google.auto.value.**
-dontwarn com.google.mediapipe.proto.CalculatorProfileProto$CalculatorProfile
-dontwarn com.google.mediapipe.proto.GraphTemplateProto$CalculatorGraphTemplate

If a release build then fails at run time with UnsatisfiedLinkError or a missing MediaPipe class, also add:

# MediaPipe
-keep class com.google.mediapipe.** { *; }

# Protocol Buffers
-keep class com.google.protobuf.** { *; }
-dontwarn com.google.protobuf.**

Android architecture support

MediaPipe text inference (.task / .bin) works on arm64-v8a, x86_64, and armeabi-v7a. Everything backed by libLiteRtLm (.litertlm inference, including its vision and audio input, embedding via LiteRT FFI, speech) is arm64-v8a only:

If your app uses only the arm64-only features, restrict the build to arm64 so the Play Store does not offer broken APKs to incompatible devices:

android {
    defaultConfig {
        ndk { abiFilters 'arm64-v8a' }
    }
}

Web#

On web, MediaPipe ignores preferredBackend and always runs on the GPU (WebGPU); ONNX honours PreferredBackend.cpu by pinning WASM.

Every web app needs flutter_gemma's model storage helpers. Copy cache_api.js and opfs_helper.js from the flutter_gemma package's web/ directory into your app's web/ (find the package directory with grep -A1 '"name": "flutter_gemma"' .dart_tool/package_config.json), then load them in web/index.html:

<script src="cache_api.js"></script>
<script src="opfs_helper.js"></script>

Then add the CDN script(s) for the engine package(s) you use.

flutter_gemma_mediapipe (.task / -web.task models):

<script type="module">
import { FilesetResolver, LlmInference } from 'https://cdn.jsdelivr.net/npm/@mediapipe/[email protected]';
window.FilesetResolver = FilesetResolver;
window.LlmInference = LlmInference;
</script>

flutter_gemma_litertlm (.litertlm web models — early preview). The @litert-lm/core ESM doesn't assign window globals and module scripts are deferred, so Dart must await window.litertLmReady before any static interop:

<script type="module">
window.litertLmReady = (async () => {
  const m = await import('https://cdn.jsdelivr.net/npm/@litert-lm/[email protected]/+esm');
  window.Engine = m.Engine;
  return m.Engine;
})();
</script>

flutter_gemma_onnx (ONNX models on Web): generation runs on Transformers.js v4, embeddings on onnxruntime-web. Both are readiness-handshake shims, same shape as the litertLmReady promise above:

<script type="module">
window.transformersReady = (async () => {
  const m = await import('https://cdn.jsdelivr.net/npm/@huggingface/[email protected]');
  window.transformers = m;
  return m;
})();
</script>

<script type="module">
window.ortReady = (async () => {
  const m = await import('https://cdn.jsdelivr.net/npm/[email protected]/dist/ort.bundle.min.mjs');
  m.env.wasm.wasmPaths = 'https://cdn.jsdelivr.net/npm/[email protected]/dist/';
  window.ort = m;
  return m;
})();
</script>

Only add the shim(s) for the arm(s) you use — transformersReady for OnnxEngine, ortReady for OnnxEmbeddingBackend.

LiteRtEmbeddingBackend (web embeddings, flutter_gemma_litertlm): runs on LiteRT.js through flutter_gemma_embeddings' web/litert_embeddings.js. Load it pinned to a release tag with a Subresource-Integrity hash — the flutter_gemma_embeddings README has the tag and how to compute the hash:

<script type="module"
        src="https://cdn.jsdelivr.net/gh/DenisovAV/flutter_gemma@<tag>/packages/flutter_gemma_embeddings/web/litert_embeddings.js"
        integrity="sha384-<hash>"
        crossorigin="anonymous"></script>

flutter_gemma_rag_sqlite (web RAG): no <script>. Copy the package's web/rag/sqlite3.wasm (a sqlite3.wasm with sqlite-vec statically linked) into your app's web root as rag/sqlite3.wasm, and serve the app with the cross-origin isolation headers OPFS persistence needs:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Desktop (macOS, Windows, Linux)#

Desktop is served primarily by flutter_gemma_litertlm (.litertlm files) — the default engine, whose native library is fetched at build time by the package's Native-Assets hook (no manual download/bundling). flutter_gemma_onnx (ONNX Runtime) also runs on all three desktop OSes (macOS/Windows/Linux), and on macOS the OS built-in model is available via flutter_gemma_builtin_ai (Apple Foundation Models, macOS only — not Windows/Linux). What holds across all of desktop: there is no MediaPipe engine on desktop — .task / .bin models are NOT compatible with desktop.

See Desktop Support for the full per-platform reference (macOS Podfile post_install, entitlements, Windows VC++ runtime, Linux Vulkan driver, and known limitations).

Platform & architecture support#

The plugin ships native prebuilts only for the architectures below. Other ABIs fail at native load with a typed error.

¹ MediaPipe text inference also works on Android x86_64 / armeabi-v7a (see the Android section above).

For development, prefer an Apple Silicon Mac — the Android emulator runs arm64-v8a natively, and macOS / iOS Simulator builds are arm64.

HuggingFace authentication#

Many models require authentication to download from HuggingFace. Never commit tokens to version control.

Recommended: config.json pattern#

Create a config template config.json.example:

{
  "HUGGINGFACE_TOKEN": ""
}

Copy it and add your token from huggingface.co/settings/tokens:

cp config.json.example config.json

Add config.json to .gitignore, then run with the config:

flutter run --dart-define-from-file=config.json

Access it in code:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  const token = String.fromEnvironment('HUGGINGFACE_TOKEN');

  await FlutterGemma.initialize(
    huggingFaceToken: token.isNotEmpty ? token : null,
  );

  runApp(MyApp());
}

Which models require authentication?#

Gated (auth required): Gemma3n (E2B, E4B), Gemma 3 1B, Gemma 3 270M, EmbeddingGemma.

Public (no auth): Gemma 4 (the litert-community builds), DeepSeek, Qwen3, Qwen 2.5, SmolLM, LFM2.5, Phi-4, FastVLM.

To use a gated repo: visit the model page → "Request Access" button.

Logging#

The plugin's internal logs are silent in release builds — model output, prompts, and conversation history are never written to logcat / syslog. In debug builds they're shown according to FlutterGemma.logLevel:

import 'package:flutter_gemma/flutter_gemma.dart';

// See the model's generated tokens and prompts while debugging:
FlutterGemma.logLevel = GemmaLogLevel.verbose;

// Or silence the plugin entirely:
FlutterGemma.logLevel = GemmaLogLevel.none;

Release builds are always silent regardless of this setting. The level is process-global and per-isolate; set it once at startup.