Installation

Android#

GPU (any engine): if you want to run on the GPU, add OpenCL support to the manifest. Required by both inference engines. CPU-only? Skip this step. Add the following above </application> in AndroidManifest.xml:

<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, so release builds work out of the box. If you still hit UnsatisfiedLinkError / missing MediaPipe classes, add to your proguard-rules.pro:

# MediaPipe
-keep class com.google.mediapipe.** { *; }
-dontwarn 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 else (.litertlm FFI, embedding via LiteRT FFI, image generation) 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#

Web runs on the GPU backend only (MediaPipe has no web CPU backend). Add the CDN script(s) for the engine package(s) you use to your web/index.html.

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_rag_sqlite (web RAG): add the wa-sqlite loader; see that package's README for the exact <script> + Subresource-Integrity hash.

Desktop (macOS, Windows, Linux)#

Desktop is served exclusively by flutter_gemma_litertlm and uses LiteRT-LM format only (.litertlm files). There is no MediaPipe engine on desktop — .task / .bin models are NOT compatible with desktop. The native library is fetched at build time by the package's Native-Assets hook — no manual download/bundling.

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() {
  WidgetsFlutterBinding.ensureInitialized();

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

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

  runApp(MyApp());
}

Which models require authentication?#

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

Public (no auth): DeepSeek, Qwen3, Qwen 2.5, SmolLM, 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.