Flutter Development Environment Setup (Apple Silicon macOS)

This document is a complete, reproducible guide based on a real troubleshooting journey. It explains what we were trying to achieve, why each tool exists, how to install everything cleanly, and how to debug the exact problems we encountered.

It is designed so that you can:

• Uninstall everything


• Reinstall from scratch


• Understand why each step exists


• Recover quickly if something breaks again

1. Goal: What We Were Trying to Achieve

We wanted a stable Flutter development environment on Apple Silicon macOS that can:

• Build and run an existing Flutter Android app (using a physical Android device)


• Compile and run the same Flutter codebase for iOS
  


• Build and run the app as a native macOS desktop app
  


• Avoid Android emulators (low-RAM optimization)


• Be repeatable and understandable

2. Mental Model: How the Tools Fit Together

Flutter

• The orchestrator
  


• Reads your Dart code


• Decides which platform you are targeting


• Delegates work to platform-specific tools

Dart

• The programming language of your app


• Bundled with Flutter (you don’t install it separately)

Android Studio

• 
  Not required to build Flutter apps


• 
  

  Used mainly to:

  
  
  
  
  
  • Download Android SDK components
  
  
  • Manage SDK versions
  
  
  • Debug Android-specific issues
  
  
  
  
  
  

Android SDK

• Required to build Android apps


• 
  

  Contains:

  
  
  
  
  
  • 
    adb (talks to your Android phone)
  
  
  • build-tools
  
  
  • platform-tools
  
  
  
  
  
  

Android Command-Line Tools

• Provide sdkmanager
  


• 
  

  Required for:

  
  
  
  
  
  • Accepting Android licenses
  
  
  • Verifying SDK correctness
  
  
  
  
  
  




• Flutter depends on these directly

Java (JDK)

• Android build tools are written in Java


• 
  

  Required for:

  
  
  
  
  
  • sdkmanager
  
  
  • Gradle builds
  
  
  
  
  
  




• Java must be visible to macOS (JAVA_HOME must be correct)

Xcode

• Required for any iOS or macOS build


• 
  

  Provides:

  
  
  
  
  
  • iOS simulator
  
  
  • macOS compiler
  
  
  • Code signing
  
  
  
  
  
  

CocoaPods

• iOS dependency manager


• Required because Flutter plugins include native iOS code

3. Clean Install Order (Recommended)

3.1 Install Xcode

1. Install Xcode from the App Store


2. Open Xcode once


3. Accept license:
   

   sudo xcodebuild -license accept

1. Install command-line tools:
   

   xcode-select --install

3.2 Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Add to PATH (Apple Silicon):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

eval "$(/opt/homebrew/bin/brew shellenv)"

3.3 Install Java (Android requirement)

Install Java 17:

brew install openjdk@17

Make macOS aware of Java:

sudo ln -sfn \

  /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk \

  /Library/Java/JavaVirtualMachines/openjdk-17.jdk

Set JAVA_HOME dynamically:

echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc

echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc

source ~/.zshrc

Verify:

java -version

/usr/libexec/java_home

3.4 Install Flutter (Official ZIP – NOT Homebrew)

1. Download Flutter macOS Apple Silicon zip


2. Extract via Terminal (avoid Finder quarantine issues):
   

   cd ~/Downloads

   unzip flutter_macos_arm64*.zip

   mv flutter ~/development/

1. Remove quarantine:
   

   xattr -dr com.apple.quarantine ~/development/flutter

1. Add to PATH:
   

   echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.zshrc

   source ~/.zshrc

1. Verify:
   

   flutter --version

3.5 Install Android Studio

1. Download Apple Silicon version


2. Drag Android Studio.app into /Applications
   


3. Remove quarantine:
   

   sudo xattr -dr com.apple.quarantine "/Applications/Android Studio.app"

1. Launch Android Studio

3.6 Install Android SDK + Command-Line Tools

In Android Studio:

1. Open SDK Manager
   


2. Set SDK location:
   

   /Users/<your-user>/Library/Android/sdk

1. Install:

• Android SDK Platform


• Build-Tools


• Platform-Tools


• Command-line Tools (latest)

Verify:

ls ~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager

Set environment:

echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc

echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin"' >> ~/.zshrc

source ~/.zshrc

Accept licenses:

flutter doctor --android-licenses

3.7 Install CocoaPods (iOS requirement)

brew install cocoapods

pod --version

3.8 Install iOS Simulator Runtime

In Xcode:

• Xcode → Settings → Components


• Install latest iOS Simulator runtime

Verify:

xcrun simctl list runtimes

4. Building Your Flutter App

Android (Physical Device)

flutter run -d android

iOS (Simulator)

cd ios

pod install

cd ..

flutter run -d ios

macOS Desktop

flutter config --enable-macos-desktop

flutter pub get

flutter run -d macos

Release build:

flutter build macos

5. Troubleshooting Reference (Problems We Solved)

Problem: “dart is damaged and can’t be opened”

Cause: macOS quarantine

Fix:

xattr -dr com.apple.quarantine ~/development/flutter

Problem: Android SDK exists but Flutter can’t find it

Cause: Missing command-line tools

Fix: Install cmdline-tools/latest and verify sdkmanager

Problem: sdkmanager exists but fails with JAVA_HOME error

Cause: Homebrew Java not visible to macOS

Fix: Symlink Java into /Library/Java/JavaVirtualMachines and set JAVA_HOME dynamically

Problem: /usr/libexec/java_home returns nothing

Cause: Java installed but not registered with macOS

Fix: Manual symlink (see Java section)

Problem: Android Studio installed but no SDK directory

Cause: SDK Manager never ran

Fix: Install SDK via Android Studio → SDK Manager

Problem: iOS simulator missing

Cause: No simulator runtime downloaded

Fix: Xcode → Settings → Components → Install iOS runtime

Problem: Chrome warning in flutter doctor

Meaning: Only affects Flutter Web

Fix (optional): Set CHROME_EXECUTABLE to Brave or install Chrome

6. Key Takeaways

• Flutter is the coordinator, not the builder


• Android Studio is optional but useful


• Java is critical for Android builds


• macOS security (Gatekeeper) causes most install pain


• Once installed correctly, daily Flutter work is simple

7. Final Verification

Run:

flutter doctor

You should see:

• Flutter ✓


• Android toolchain ✓


• Xcode ✓ (after simulator install)

This guide reflects a real-world, non-ideal setup path, which makes it far more valuable than a clean tutorial. You now understand not just how to install Flutter — but why it breaks and how to recover.