DEV Community

cycy
cycy

Posted on

Flutter Development Environment Setup (Apple Silicon macOS)

#flutter #mobile #tooling #tutorial

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
Enter fullscreen mode Exit fullscreen mode
  1. Install command-line tools: 
   xcode-select --install
Enter fullscreen mode Exit fullscreen mode

3.2 Install Homebrew 

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

Add to PATH (Apple Silicon):

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

3.3 Install Java (Android requirement)

Install Java 17:

brew install openjdk@17
Enter fullscreen mode Exit fullscreen mode

Make macOS aware of Java:

sudo ln -sfn \
  /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk \
  /Library/Java/JavaVirtualMachines/openjdk-17.jdk
Enter fullscreen mode Exit fullscreen mode

Set JAVA_HOME dynamically:

echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

Verify:

java -version
/usr/libexec/java_home
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode
  1. Remove quarantine: 
   xattr -dr com.apple.quarantine ~/development/flutter
Enter fullscreen mode Exit fullscreen mode
  1. Add to PATH: 
   echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.zshrc
   source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode
  1. Verify: 
   flutter --version
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode
  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
Enter fullscreen mode Exit fullscreen mode
  1. Install:
  • Android SDK Platform
  • Build-Tools
  • Platform-Tools
  • Command-line Tools (latest)

Verify:

ls ~/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Accept licenses:

flutter doctor --android-licenses
Enter fullscreen mode Exit fullscreen mode

3.7 Install CocoaPods (iOS requirement) 

brew install cocoapods
pod --version
Enter fullscreen mode Exit fullscreen mode

3.8 Install iOS Simulator Runtime

In Xcode:

  • Xcode → Settings → Components
  • Install latest iOS Simulator runtime

Verify:

xcrun simctl list runtimes
Enter fullscreen mode Exit fullscreen mode

4. Building Your Flutter App

Android (Physical Device) 

flutter run -d android
Enter fullscreen mode Exit fullscreen mode

iOS (Simulator) 

cd ios
pod install
cd ..
flutter run -d ios
Enter fullscreen mode Exit fullscreen mode

macOS Desktop 

flutter config --enable-macos-desktop
flutter pub get
flutter run -d macos
Enter fullscreen mode Exit fullscreen mode

Release build:

flutter build macos
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.