flutter_rust: Flutter + Rust FFI for high-performance Flutter apps

Call Rust from Flutter/Dart with dart:ffi: no codegen, zero-copy, built automatically by native assets. Real-time path tracing, photo recoloring, photo to coloring page, a spreading fill, pixel-art flood fill, falling sand, image processing, hashing and sorting run 1.5× to 21× faster than pure Dart. Every number is benchmarked and every result is verified by tests.

Demo video · Quick start · Benchmarks · API · Demo app · FAQ

flutter_rust is a complete, working answer to "how do I use Rust in Flutter to speed up my app?". It contains:

• fast_rust: a Dart/Flutter library whose heavy lifting is written in Rust and called directly through dart:ffi @Native functions.
• fast_rust_demo: a Flutter app that runs Dart and Rust side by side on the same input, so you can see the difference on your own phone.

It is a good fit for CPU-heavy work in Flutter apps:

• photo editing (recolor hair, sky or clothes while keeping texture);
• image processing (blur, grayscale, filters);
• coloring and pixel-art apps (flood fill, paint bucket, a fill that spreads from the finger);
• hashing and crypto (SHA-256);
• sorting large datasets;
• scientific computing;
• graphics rendering (fractals);
• signal processing.

These are jobs where pure Dart, even with compute() or isolates, is not fast enough.

• ⚡ Fast calls: one FFI call costs about 1.5 ns. Rust reads and writes Dart's Uint8List/Float64List in place. Unlike platform channels, nothing is copied or serialized.
• 🔧 No native setup: a build hook (native assets) runs cargo automatically on flutter run, flutter build and flutter test. You don't edit Gradle, CMake or Podspecs, and you don't copy .so or .dylib files by hand.
• 🖌️ Recolor real photos: tap the hair and it turns pink, with every strand still visible. A magic-wand selection over the original pixels plus a brightness-preserving tint; a tap on a 505×607 photo takes 0.05 to 1.3 ms.
• 🔮 Real-time path tracing: glass, metal and diffuse spheres with soft shadows, reflections, refraction and depth of field. The picture sharpens as samples accumulate on every core: one 480×360 sample takes 4.9 ms on 8 threads, against 63 ms in Dart (12.8×). Drag to orbit.
• 🖍️ Photo to coloring page: any photo becomes black outlines on white, with closed regions ready to fill (blur, k-means, cleanup, outlines). It takes about 116 ms in Rust and 730 ms in Dart for 1920×1080. Color splash comes for free: gray the photo, then restore regions with strength: 0.
• ⏳ Falling sand: a million cells of sand, water and walls are stepped every frame by a deterministic cellular automaton.
• 🌊 Spreading fill: the color flows out from the finger as a round wave that follows the region's shape (geodesic distances, Dijkstra with a bucket queue).
• 🎨 Smooth pixel-art coloring: flood-filling a solid 2-megapixel region takes about 3 ms (Dart: 12 ms). A region of a few thousand pixels takes about 0.1 ms, which is fast enough to paint continuously as your finger drags.
• 🧵 Real multi-threading: Rust spreads work over every CPU core with a load-balancing work queue. On an Apple M4, Mandelbrot runs 7.3× faster.
• 📱 No UI jank: the ...Async functions run on a background isolate with non-leaf calls, so they block neither the UI thread nor the GC.
• ✅ Verified: 79 tests across Rust, Dart and Flutter.
  • Rust output matches the pure-Dart implementation bit for bit.
  • SHA-256 output matches package:crypto.
• 📦 Small: the Rust crate has zero dependencies, builds offline and is easy to audit.

Real-time path tracing	Photo to coloring page	Color splash	Falling sand (1M cells)
Samples accumulate every frame, so the image sharpens in seconds; drag to orbit	Rust turns the photo into outlines; tap regions to fill; Reveal uses the photo's own colors	Gray canvas; each tap copies the original colors of one region back	Pour sand and water, draw walls, add rain; switch to Dart and watch the FPS

Photo recoloring in Rust	Pixel-art coloring in Rust	Fractal explorer in Rust	Real-time blur on the UI thread
Tap or drag with Spread on: the color flows along the hair; selection reads the original pixels	Tap or drag to fill; a ~2,400 px region took 0.07 ms (single sample, test environment)	Renders in the background on 10 Rust threads; the UI stays smooth while zooming	A 1280×800 box blur takes 7.2 ms/frame, within the 60 fps budget

61 seconds of real app footage:

1. Photo recoloring with the spreading fill.
2. Color splash.
3. The photo turned into a coloring page, filled region by region, then Reveal.
4. Falling sand, switched between Rust and Dart.
5. Real-time path tracing: the image sharpens, an orbit restarts it, and the Dart engine is switched in for comparison.
6. The pixel-art coloring book: spread, drag, and Auto mode.
7. A fractal zoom. It is recorded headless by examples/fast_rust_demo/tool/video_test.dart. Full quality: docs/video/demo.mp4.

These are real screenshots of the app, rendered headless with flutter test; see section 15. The millisecond values were measured in a desktop test environment, not on a phone.

1. Benchmark results
2. Repository layout
3. Requirements
4. Quick start
5. Using the library in your app
6. API
7. Sync or async: the leaf-call rule
8. Architecture
9. Demo app
10. Tests and benchmarks
11. Adding a new Rust function
12. Troubleshooting
13. Verification status and limitations
14. FAQ
15. Regenerating the README images and numbers

Machine: Apple M4 (10 threads), macOS. Built AOT (dart build cli, equivalent to a release build); each value is the median of 9 runs after warm-up. Raw data is in docs/benchmark.json.

• Rust 1T: Rust limited to one thread (single-core speed).
• Rust 10T: Rust using all threads.
• Dart always runs on a single thread.

Newer kernels. These were measured later on a different machine (Apple M1 Pro, 8 threads, under background load), so compare them only with each other. The recolor and spreading-fill rows use a solid 1920×1080 region, which selects the whole frame:

The sand step is a sequential, branchy scan that AOT Dart handles well, so Rust gains only 1.5× there. A tapped region in a real photo is usually far smaller than the whole frame. In the demo, one tap on 505×607 px takes 0.05 to 1.3 ms.

One FFI call (leaf call, AOT) costs about 1.5 ns. Results vary by about ±15% between runs; for example, the 10-thread blur has measured anywhere from 2.6 to 4.8 ms.

How to read these numbers:

• Flood fill is sequential and cannot be split across threads, so its 4× comes entirely from single-core speed. Rust compares whole 4-byte pixels and fills each span with a vectorized store loop. The benchmark fills a solid rectangle, which is the easiest case for a scanline fill; irregular regions cost more per pixel.
• Same algorithm on both sides, with two exceptions:
  • SHA-256: the Dart side is package:crypto.
  • Sort: the Dart side is List.sort, which calls a comparator closure for every comparison; the Rust side is pdqsort. Most of the 21× comes from Dart's comparator overhead.
• Mandelbrot: for a simple floating-point loop like this one, AOT Dart is about as fast as Rust on one core (1.2×). The 7.3× comes entirely from multi-threading.
• Phones will differ: these numbers come from one desktop machine. Run the demo app with --profile or --release on a real device to get your own.
• When not to use FFI: when each call does only a few nanoseconds of work. The win comes from moving whole loops into Rust, not individual operations.

_{Before and after FastRust.boxBlurRgba (radius 18). The source image is also rendered by FastRust.mandelbrotRgba.}

flutter_rust/
├── packages/fast_rust/              # The library (pure Dart package, works in Flutter too)
│   ├── rust/                        # Rust crate (cdylib, zero dependencies)
│   │   ├── Cargo.toml               # Release profile: LTO, opt-level 3, panic=abort
│   │   └── src/
│   │       ├── lib.rs               # C ABI: the fr_* functions exported to Dart
│   │       ├── parallel.rs          # Row-band splitting, work queue, thread limit
│   │       ├── hash.rs              # SHA-256 (FIPS 180-4)
│   │       ├── image.rs             # Grayscale, separable box blur
│   │       ├── fractal.rs           # Mandelbrot
│   │       ├── coloring.rs          # Coloring pages, flood fill, photo recolor, spreading fill
│   │       ├── lineart.rs           # Photo to coloring page: blur, k-means, cleanup, outlines
│   │       ├── sand.rs              # Falling-sand cellular automaton
│   │       ├── raytrace.rs          # Progressive path tracer (spheres, glass, metal, depth of field)
│   │       └── numeric.rs           # f64 sort, prime sieve, dot product
│   ├── hook/build.dart              # Build hook: runs cargo for the right target, registers the CodeAsset
│   ├── lib/
│   │   ├── fast_rust.dart           # Public entry point
│   │   └── src/
│   │       ├── bindings.dart        # @Native declarations (leaf and non-leaf)
│   │       ├── api.dart             # Safe API: class FastRust
│   │       └── dart_reference.dart  # Same algorithms in pure Dart (oracle and baseline)
│   ├── test/fast_rust_test.dart     # 43 tests: correctness, validation, async, coloring, recolor, sand, path tracing
│   ├── example/fast_rust_example.dart # Command-line tour: every kernel in Rust and Dart, outputs compared
│   ├── benchmark/benchmark.dart     # Command-line benchmark (--json exports results)
│   └── tool/readme_images.dart      # Generates the README charts and images from real output
└── examples/fast_rust_demo/         # Flutter demo app
    ├── lib/
    │   ├── main.dart                # 7 tabs, each built on first visit
    │   ├── benchmarks.dart          # Benchmark cases run on a background isolate
    │   ├── engine.dart              # Rust/Dart enum, RGBA to ui.Image
    │   ├── spread.dart              # One running spreading-fill animation
    │   └── pages/                   # benchmark, fractal, blur, paint, photo, sand and ray pages
    ├── test/app_test.dart           # Widget tests (load the real Rust library through native assets)
    ├── assets/photo.jpg             # Photo used by the Photo tab
    └── tool/                        # screenshots_test.dart, video_test.dart, make_video.sh
docs/
├── benchmark.json                   # Raw results behind the table and charts
├── images/                          # Banner, charts, app screenshots, Rust-rendered images
└── video/                           # demo.mp4 and demo.gif, recorded from the real app

Add the Rust targets for the platforms you build for:

# Android
rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android i686-linux-android
# iOS (devices + simulator)
rustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
# macOS
rustup target add aarch64-apple-darwin x86_64-apple-darwin
# Linux / Windows
rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
rustup target add x86_64-pc-windows-msvc aarch64-pc-windows-msvc

• Android: requires the Android NDK. Flutter passes the NDK's clang path to the build hook, which uses it as the linker.
• iOS/macOS: require Xcode.
• cargo on PATH: cargo must be on PATH. If it isn't, the hook falls back to ~/.cargo/bin/cargo, because IDEs launched from the GUI often lack that path.

git clone <repo> flutter_rust && cd flutter_rust

# 1. Test the library (the first run builds Rust, which takes a few seconds)
cd packages/fast_rust
dart pub get
dart test

# 2. Benchmark
dart run benchmark/benchmark.dart                # JIT (like debug builds)
dart build cli -t benchmark/benchmark.dart       # AOT (like release builds)
./build/cli/*/bundle/bin/benchmark

# 3. Run the demo app
cd ../../examples/fast_rust_demo
flutter pub get
flutter test
flutter run --release        # or --profile; debug builds run Dart in JIT mode and are slower

Add the dependency from pub.dev:

flutter pub add fast_rust

You also need Rust ≥ 1.88 and the Rust targets for your platforms (see section 3); the build hook compiles the crate on your machine.

Examples:

import 'dart:typed_data';
import 'package:fast_rust/fast_rust.dart';

// Hashing: zero-copy, synchronous
final Uint8List digest = FastRust.sha256(bytes);

// A small blur inside a frame: edits the RGBA buffer in place
FastRust.boxBlurRgba(pixels, width: w, height: h, radius: 10);

// Heavy work: runs on a background isolate, blocks neither the UI nor the GC
final Uint8List blurred =
    await FastRust.boxBlurRgbaAsync(bigImage, width: W, height: H, radius: 30);

final Uint8List fractal = await FastRust.mandelbrotRgbaAsync(
  width: 800,
  height: 600,
  scale: 3 / 800,          // size of one pixel in the complex plane
  maxIterations: 500,
);

// Pixel-art coloring: generate a page, then "pour paint" into the tapped region
final page = FastRust.coloringPageRgba(width: 1024, height: 1024, cells: 140, block: 8);
final painted = FastRust.floodFillRgba(page,
    width: 1024, height: 1024, x: tapX, y: tapY, color: 0x2A9D8FFF);

// Photo recoloring: select by color around the tap and tint, keeping texture.
// `source` is the decoded photo (never modified), `canvas` a copy you display.
FastRust.recolorRegionRgba(source, canvas,
    width: w, height: h, x: tapX, y: tapY, color: 0xFF4D8DFF, tolerance: 28);

// Spreading fill: distances once, then one ring per frame.
final dist = Uint32List(w * h);
final maxDist = FastRust.spreadDistancesRgba(source, dist,
    width: w, height: h, x: tapX, y: tapY, tolerance: 28);
FastRust.paintByDistanceRgba(source, canvas, dist,
    width: w, height: h, from: previousRadius, to: radius,
    color: 0xFF4D8DFF, tint: true);   // tint: false paints a flat color

// In-place sort (IEEE-754 total order)
FastRust.sortFloat64(values);
final sorted = await FastRust.sortFloat64Async(hugeList);   // returns a sorted copy

// Showing an RGBA buffer in Flutter
ui.decodeImageFromPixels(fractal, 800, 600, ui.PixelFormat.rgba8888, (img) {
  // use with RawImage(image: img)
});

Native errors are thrown as FastRustException (null pointer, invalid argument, out of memory). Invalid Dart arguments throw ArgumentError or RangeError before anything is sent to Rust.

Everything lives in abstract final class FastRust.

Input limits (exceeding them throws RangeError):

NaN order when sorting: -NaN < -∞ < … < -0.0 < 0.0 < … < ∞ < NaN. This differs from Dart's List.sort, which puts every NaN last.

DartReference provides the same functions in pure Dart. They are used by the tests and as the benchmark baseline.

This is the most important thing to understand about high-performance FFI.

Leaf calls (@Native(isLeaf: true)):

• They are the cheapest kind of call, because the thread never leaves the Dart VM.
• They are the only kind that may receive typedList.address, a pointer straight into the Dart heap with no copy.
• The trade-off: while a leaf call runs, GC is paused for every isolate in the group, including the UI isolate, even if you call it from Isolate.run.

Non-leaf calls:

• The thread leaves the VM, so other isolates keep collecting garbage.
• They cannot take pointers into the Dart heap, so they must use native memory (malloc).

How the library uses them:

Rule of thumb: if a call can take more than about 4 ms on a phone (a quarter of a 16.7 ms frame), use the Async version.

 Dart / Flutter app
        │  FastRust.boxBlurRgba(pixels, …)
        ▼
 lib/src/api.dart          validates arguments, picks leaf or non-leaf
        │
 lib/src/bindings.dart     @Native<…>(symbol: 'fr_box_blur_rgba', isLeaf: true)
        │                  asset id = package:fast_rust/src/bindings.dart
        ▼
 libfast_rust.{so,dylib,dll}   ← built and bundled by hook/build.dart
        │
 rust/src/lib.rs           extern "C" fr_*: checks nulls and sizes, returns an i32 status
        ▼
 rust/src/image.rs …       pure Rust kernels, parallelized via parallel.rs

Build hook (hook/build.dart):

1. The Dart or Flutter SDK runs the hook with the current target OS and architecture.
2. The hook maps it to a Rust target triple: for example, android/arm64 becomes aarch64-linux-android, and iOS simulator/arm64 becomes aarch64-apple-ios-sim.
3. The hook runs cargo rustc --release --lib --crate-type cdylib --target <triple>. Output goes into the hook's cache directory (.dart_tool/…), so later builds are incremental.
   • On Android, the hook links with the NDK's clang wrapper (<triple><api>-clang) and adds -z max-page-size=16384 to support devices with 16 KB pages (Android 15+).
   • On Apple platforms, it sets MACOSX_DEPLOYMENT_TARGET or IPHONEOS_DEPLOYMENT_TARGET from Flutter's configuration.
4. The hook registers CodeAsset(name: 'src/bindings.dart', linkMode: DynamicLoadingBundled()). The SDK bundles the library into the app (APK, framework, bundle). The @Native functions in bindings.dart resolve their symbols automatically, with no DynamicLibrary.open.
5. The hook declares every file in rust/src/ as a dependency, so editing Rust code triggers a rebuild.

C ABI conventions (rust/src/lib.rs):

• Every fr_* function takes a pointer plus a length and never allocates memory that crosses the FFI boundary. The caller owns the memory.
• Functions return an i32: 0 means OK, -1 a null pointer, -2 an invalid argument. The Dart side turns these codes into FastRustExceptions.
• With len == 0, the pointer is never dereferenced.
• With panic = "abort" and all inputs validated up front, no unwinding can cross the FFI boundary.

Multi-threading (rust/src/parallel.rs):

• Data is split into bands of rows, about 16K elements each.
• The bands sit in a shared, mutex-protected queue, so threads that finish early pick up more work. This matters for uneven loads like fractals: moving from a fixed split to the queue took Mandelbrot from 3.6× to 6.8× (measured under JIT).
• The calling thread works too, and small inputs run on it directly to avoid spawn overhead.
• Kernels have two ways to adjust band sizes:
  • Kernels with per-band setup cost, such as the blur's vertical window, ask for taller bands via min_band_rows.
  • Kernels that are expensive per element, such as the coloring page's region search, set an explicit band height via for_each_band_of.

O(pixels) box blur: the blur makes two passes, horizontal then vertical. Each pass keeps a running sum, and samples clamped at the image edge are counted by multiplication instead of looping, so the cost does not depend on the radius.

examples/fast_rust_demo has 7 tabs. Each tab is built on first visit, so no heavy work runs at startup.

Run it:

cd examples/fast_rust_demo
flutter run --profile      # representative numbers; use --release for the real experience

Lints: cargo clippy --release --all-targets, dart analyze, flutter analyze. App screenshots are not part of the normal test suite; generate them separately with flutter test tool/screenshots_test.dart --update-goldens.

1. Rust: write the kernel in a module, then export it from rust/src/lib.rs:

   #[no_mangle]
   pub unsafe extern "C" fn fr_invert_rgba(rgba: *mut u8, len: usize) -> i32 {
       if len % 4 != 0 { return Status::InvalidArgument as i32; }
       let rgba = try_slice!(slice_mut(rgba, len));
       for px in rgba.chunks_exact_mut(4) { px[0] = !px[0]; px[1] = !px[1]; px[2] = !px[2]; }
       Status::Ok as i32
   }

2. Binding: declare it in lib/src/bindings.dart.

   • Use a leaf call for short work on Dart buffers.
   • Use a non-leaf call (drop isLeaf) with native memory for long work.

   @Native<Int32 Function(Pointer<Uint8>, Size)>(symbol: 'fr_invert_rgba', isLeaf: true)
   external int frInvertRgba(Pointer<Uint8> rgba, int len);

3. API: wrap it in FastRust (lib/src/api.dart), validate the arguments, then call _check(...).

4. Test: add a Dart version to DartReference and a test in test/fast_rust_test.dart that compares the two.

5. If you change the signature of an existing function, bump fr_abi_version.

No build-hook changes are needed: every file in rust/src/ is already tracked.

Verified on macOS arm64:

• cargo test and clippy.
• dart test and dart analyze.
• flutter test and flutter analyze. In all three test environments, the Rust library is built and loaded through native assets.
• JIT and AOT benchmarks.

Not yet verified: app builds for Android, iOS and desktop. The logic for target triples, the NDK linker and deployment targets is written and reviewed, but has not been run on those platforms.

Known limitations:

• Each parallel call spawns fresh threads; there is no persistent thread pool yet. That costs a few tens of µs per call, which may matter for per-frame blur on Android.
• Several isolates calling parallel functions at once can oversubscribe the CPU cores.
• Sync leaf functions still pause GC while they run (see section 7).
• Photo selection compares each pixel with the tapped one, so regions whose color is close to a neighbor's (blonde hair next to skin) can leak. Lower the tolerance or tap several times.

Every image in docs/images except the banner is produced by the library itself, so you can check them yourself:

cd packages/fast_rust
dart build cli -t benchmark/benchmark.dart
./build/cli/*/bundle/bin/benchmark --json=../../docs/benchmark.json   # measurements
dart run tool/readme_images.dart ../../docs                           # SVG charts, fractal, blur

cd ../../examples/fast_rust_demo
flutter test tool/screenshots_test.dart --update-goldens              # app screenshots
flutter test tool/video_test.dart && tool/make_video.sh               # demo video (needs ffmpeg)

Keywords: Flutter Rust · Flutter FFI · dart:ffi · call Rust from Flutter · Flutter performance optimization · speed up Flutter · native assets · build hooks · Flutter image processing · Flutter photo editor · recolor image · magic wand · Flutter coloring app · photo to line art · coloring page generator · color splash · falling sand · cellular automaton · path tracing · ray tracing in Flutter · flood fill · spreading fill · pixel art · coloring book · Rust cdylib · flutter_rust_bridge alternative · Dart isolate · Flutter performance

If you find this useful, please ⭐ the repo so more people can find it.

Released under the MIT License.