flutter_compat

Analyze Flutter project compatibility across environment, dependencies, Android, and iOS — before you add packages or upgrade.

Like flutter doctor and dart pub outdated, with deeper cross-platform checks.

Install

dart pub global activate flutter_compat

Or run from source:

dart pub get
dart run flutter_compat doctor

Commands

doctor

Scan the complete project and print a human-readable report.

flutter_compat doctor
flutter_compat doctor --packages
flutter_compat doctor -v

Example:

✓ Flutter 3.44.9 (stable)
✓ Dart 3.12.2
✓ Gradle 8.14
✓ AGP 8.8.2
✓ Kotlin 2.1.20
✓ JDK 17
✓ Xcode 16.0
✓ Swift 6.0
✓ CocoaPods 1.16.0

Warnings:
⚠ Package X requires Dart >=3.12

Errors:
✗ Kotlin incompatible with AGP

check

CI/CD validation with exit codes:

Code	Meaning
0	Success
1	Warnings
2	Errors

flutter_compat check
flutter_compat check --packages --quiet

add

Pre-flight check a package, then optionally run flutter pub add.

flutter_compat add firebase_core
flutter_compat add firebase_core --dry-run
flutter_compat add http --dev -y

Flow:

1. Fetch pub.dev metadata
2. Check Flutter / Dart / Android / iOS constraints
3. Detect conflicts & native requirements
4. Ask for confirmation
5. Run flutter pub add

remove

Safely remove a package with a pre-check.

flutter_compat remove firebase_core --dry-run
flutter_compat remove firebase_core
flutter_compat remove build_runner --dev -y

Flow:

1. Verify the package exists in dependencies / dev_dependencies
2. Ask for confirmation
3. Run flutter pub remove

update

Check whether upgrades look safe for the current toolchain.

flutter_compat update

scan

Raw scanner / environment dump (useful for debugging).

flutter_compat scan
flutter_compat scan --json

report

Write JSON, Markdown, and HTML reports.

flutter_compat report
flutter_compat report -o build/reports --packages

Outputs:

• compatibility_report.json
• compatibility_report.md
• compatibility_report.html

fix

Apply safe upgrades for Flutter Android toolchain warnings (Gradle / AGP / Kotlin / minSdk).

flutter_compat fix --dry-run
flutter_compat fix -y

This is the same class of issues Flutter prints as:

Warning: Flutter support for your project's Gradle version will soon be dropped…

Real project examples

# Check a project in another folder
flutter_compat doctor -C "/Users/fahad/Documents/The Xpertz/cyber_fuchs_flutter"

# CI style result (0 success, 1 warnings, 2 errors)
flutter_compat check -C "/Users/fahad/Documents/The Xpertz/cyber_fuchs_flutter"

# See what fixes would be applied
flutter_compat fix --dry-run -C "/Users/fahad/Documents/The Xpertz/cyber_fuchs_flutter"

Troubleshooting

Gradle download fails after fix

If you see errors like:

FileNotFoundException ... gradle-8.14.0-all.zip

run flutter_compat fix again on the project.
It now normalizes wrapper URLs to:

https://services.gradle.org/distributions/gradle-<version>-all.zip

which avoids broken GitHub distribution links in wrapper configs.

pub.dev download count not updating

pub.dev download stats are delayed and cached.
New installs may take several hours (sometimes up to a day) to appear.

Confidence levels

Symbol	Meaning
✓	Compatible
⚠	Possible conflict
✗	Confirmed issue
?	Unknown

Architecture

CLI (args / cli_util)
  └── AnalysisService
        ├── Scanners (Flutter, Dart, Pubspec, Gradle, AGP, Kotlin, JDK, Android, iOS, Xcode, Swift, Pods, Packages)
        ├── CompatibilityEngine + Rules matrix
        └── PubDevRepository
              └── ReportWriter / DoctorPrinter

Compatibility rules

• Flutter ↔ Dart
• Flutter ↔ Packages
• Dart ↔ Packages
• AGP ↔ Gradle
• AGP ↔ Kotlin
• Kotlin ↔ JDK
• Gradle ↔ JDK
• Package ↔ Native SDK
• Xcode ↔ Swift
• Pods ↔ Deployment Target

Development

dart pub get
dart analyze
dart test
dart run flutter_compat doctor -C test/fixtures/sample_project

Future

• VS Code / Cursor extensions
• GitHub Action
• Auto-fix expansions
• Interactive TUI / web dashboard

License

MIT