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.flutter-io.cn 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.flutter-io.cn download count not updating

pub.flutter-io.cn 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