Workaround for New Flutter Version on MacOS Catalina

The Flutter SDK is a development framework that allows developers to write code once and run on multiple platforms such as mobile, web, and desktop.

In order to do iOS development, Flutter must be run on MacOS with an XCode installation. Since Flutter 3.0, XCode 13 is required. At the time of XCode 13's and Flutter 3.0's release, September 2021 and May 2022 respectively, MacOS Catalina was supported by Apple security update (which has since ended in July 2022). XCode 13 is no longer supported by MacOS Catalina (12.4 is the last XCode supported on MacOS Catalina).

With MacOS Catalina, one is no longer able to build for the latest version of iOS through XCode or use the latest version of Flutter. For the limited number of devs still with an old (and unsupported) Mac, this is frustrating.

I discovered a workaround that allows Flutter 3 to continue building on MacOS Catalina, but keep in mind this is not supported by the Flutter team and may cause unexpected issues.

The XCode version check is done in packages/flutter_tools/lib/src/macos/xcode.dart inside the Flutter SDK root folder. To reverse the check, we need to do something opposite of what https://github.com/flutter/flutter/pull/97746 did.

For Flutter 3.0.5:

--- a/packages/flutter_tools/lib/src/macos/xcode.dart
+++ b/packages/flutter_tools/lib/src/macos/xcode.dart
@@ -18,11 +18,11 @@ import '../base/version.dart';
 import '../build_info.dart';
 import '../ios/xcodeproj.dart';

-Version get xcodeRequiredVersion => Version(13, null, null);
+Version get xcodeRequiredVersion => Version(12, 3, null, text: '12.3');

 /// Diverging this number from the minimum required version will provide a doctor
 /// warning, not error, that users should upgrade Xcode.
-Version get xcodeRecommendedVersion => xcodeRequiredVersion;
+Version get xcodeRecommendedVersion => Version(13, null, null, text: '13');

 /// SDK name passed to `xcrun --sdk`. Corresponds to undocumented Xcode
 /// SUPPORTED_PLATFORMS values.

For Flutter 3.3.10

--- a/packages/flutter_tools/lib/src/macos/xcode.dart
+++ b/packages/flutter_tools/lib/src/macos/xcode.dart
@@ -18,7 +18,7 @@ import '../base/version.dart';
 import '../build_info.dart';
 import '../ios/xcodeproj.dart';

-Version get xcodeRequiredVersion => Version(13, null, null);
+Version get xcodeRequiredVersion => Version(12, 3, null, text: '12.3');

 /// Diverging this number from the minimum required version will provide a doctor
 /// warning, not error, that users should upgrade Xcode.

Dart compiles the source on the fly when required, but if cache is available, it will use the compiled cache which will not contain our version check hack. You will need to delete the following file after making the above change:

rm bin/cache/flutter_tools.snapshot

After that, you can run your flutter normally. The first run will re-compile the flutter tools package with our version check hack.

This workaround is merely disabling the version check. As far as I know, at least for Flutter 3.0 ~ 3.0.5, the Flutter team did not add features that rely on the newer XCode version. I'm also able to use Flutter 3.3.10 on simpler projects, but I'm still testing. However, do note that if features relying on the newer XCode version are added, your build will break.

I would only recommend using this workaround for development. If you need to produce production builds, I recommend using a virtual machine with a newer MacOS version running on your Catalina host (which is painful to setup and use, but will nonetheless be able to run the latest XCode and Flutter "natively").

With all things Apple, the permanent fix is always "just buy a new Mac".

For now though, you can use continue to use your outdated Mac for a little longer.

PS: Yet another workaround is to upgrade your unsupported Mac to Big Sur/Monterey using OCLP. But at least for an iMac with an NVidia GPU, that configuration requires a little extra effort to inject the NVidia drivers and is less stable. So a few line changes in the Flutter SDK is a bit simpler by comparison.