How to Install and Set Up Flutter on macOS (Intel & Apple Silicon) – Ultimate 2025 Beginner ‑ Friendly Guide

Flutter on macOS – Step‑by‑step Flutter installation guide for macOS (M1, M2, Intel). Fix emulator code 1, CocoaPods Ruby error, and SDK tool issues in minutes.

Why another Flutter installation article? – Flutter on macOS

Most tutorials stop after “run flutter doctor.” Unfortunately, that’s the moment when beginner developers hit a wall—mysterious red errors, emulator crashes, or CocoaPods refusing to install. This guide does five things differently:

1. Context before command: every line you copy‑paste is explained in plain English so you know what it does.
2. Apple Silicon & Intel paths clearly separated. You never wonder “Does this apply to my M2 laptop?”
3. One page = zero back‑and‑forth. We cover Android Studio, Xcode, Homebrew, Ruby, rbenv, ADB, PATH variables, and common error messages in one place.
4. Step‑by‑step GUI + Terminal. Whether you love clicking or typing, you have both routes.
5. Rank Math SEO compliance. Perfect for bloggers who want high Google visibility.

Feel free to skim the Quick‑Start Checklist at the end once you’re comfortable. Let’s dive in!

1. Prerequisites & Terminology

Before touching the Terminal, let’s align on a few terms:

Term	Meaning in this guide
Flutter SDK	Toolkit that turns Dart code into native binaries.
Homebrew	Package manager for macOS. Easier than downloading .dmg files manually.
rbenv	Version manager that lets you run multiple Ruby versions safely.
SDK Manager	Android Studio panel that downloads platform & build tools.
AVD	Android Virtual Device—your emulator.

Hardware & OS

• macOS Ventura 13 or newer (Monterey 12 also works).
• 8 GB RAM minimum (emulator + Android Studio are memory‑hungry).
• 10 GB free disk space.

Intel vs Apple Silicon: type uname -m in Terminal. x86_64 = Intel; arm64 = Apple Silicon (M‑series chips).

2. Download & Verify Flutter SDK

1. Visit https://flutter.dev/docs/get-started/install/macos.
2. Click macOS – Stable ==> download flutter_macos_<version>-stable.zip.
3. Extract:mkdir -p ~/development cd ~/Downloads unzip flutter_macos_*_stable.zip mv flutter ~/development/
4. Verify signature (optional but recommended):cd ~/development/flutter shasum -a 256 flutter_macos_*_stable.zipCompare with the hash on Flutter’s release notes. Matching hashes mean the file hasn’t been tampered with.

Why the ~/development folder? Alphabet‑safe, permission‑safe, and easy to remember.

3. Add Flutter to PATH

A PATH is like a list of folders macOS searches when you type commands. We’ll append Flutter’s bin folder.

Option A – Graphical (TextEdit)

open -e ~/.zshrc

(Opens your shell config in TextEdit.)

Add the line at the bottom:

export PATH="$PATH:$HOME/development/flutter/bin"

Save ==> close ==> back to Terminal:

source ~/.zshrc
flutter --version

You should see Flutter and Dart versions printed.

Option B – VS Code Shortcut

If you prefer VS Code:

code ~/.zshrc

Paste the same export line, save, and reload.

Read also: How to Force Empty Your Mac’s Trash: A Step-by-Step Guide

4. Install Homebrew

Homebrew manages packages so you don’t hunt for installers.

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

After installation, append Brew to PATH (Apple Silicon uses /opt/homebrew):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
brew doctor   # Should say "Your system is ready to brew."

5. Install / Upgrade Ruby safely via rbenv

macOS ships Ruby 2.6 which is too old for modern CocoaPods.

brew install rbenv ruby-build
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc
rbenv install 3.2.2   # Or latest stable
rbenv global 3.2.2
ruby -v               # Should report 3.2.x

Why not sudo gem install? System Ruby is inside a read‑only directory; forcing sudo can corrupt future macOS updates.

6. Install CocoaPods

Now that Ruby 3.2.2 is active:

gem install cocoapods
pod setup   # Pre‑caches specs

Common Error:

ERROR:  While executing gem ... (Gem::FilePermissionError)

You’re still on system Ruby. Run which ruby ==> it must show your Homebrew path (/opt/homebrew/...). If not, revisit Step 5.

7. Android Studio Setup

7.1 Install Android Studio

Download the .dmg from https://developer.android.com/studio. Drag to Applications folder.

7.2 Add Flutter & Dart plugins

• Preferences ==> Plugins
• Search Flutter ==> Install ==> Dart installs automatically.

7.3 Configure Android SDK

Preferences ==> Appearance & Behavior ==> System Settings ==> Android SDK.

On the SDK Platforms tab:

• Check Android 14.0 (API 34)
• Optionally, Android 13 for backward compatibility.

On the SDK Tools tab:

• Android SDK Command‑line Tools (latest)
• Android Emulator
• Android SDK Platform‑Tools
• Android SDK Build‑Tools 35.0.0 (or latest) Click Apply. This fixes the dreaded:

cmdline-tools component is missing

error from flutter doctor.

8. Create a Kotlin‑based Flutter Project

1. Welcome Screen ==> New Flutter Project.
2. Choose Flutter Application.
3. Fill details:
   • Project name: my_first_app
   • Flutter SDK path: /Users/you/development/flutter
   • Android language: Kotlin
   • iOS language: Swift (default)
4. Click Finish (or Create depending on version). Android Studio resolves Dart packages.

You must see lib/main.dart. Missing? You accidentally chose Dart Console or Java project—repeat with correct wizard.

9. Fixing Missing SDK Tools & Licenses

Run:

flutter doctor

Typical first‑run output:

cmdline-tools component is missing.
Android license status unknown.

9.1 Accept Licenses

flutter doctor --android-licenses

Press y until done.

9.2 Still missing cmdline‑tools?

You probably skipped the SDK Tools checkbox. Re‑open SDK Manager ==> check Android SDK Command‑line Tools ==> Apply.

10. Emulator Setup for Intel vs Apple Silicon

10.1 Apple Silicon (M‑Series)

• Only arm64‑v8a images work.
• Device Manager ==> Create Device ==> Pixel 5.
• System Image tab ==> Download API 34 | arm64‑v8a.
• Graphics ==> Software if you experience black screen.

10.2 Intel Mac

• Use x86_64 or x86 images.
• Check HAXM in SDK Tools. If missing, Intel HAXM isn’t compatible with Apple Silicon, which explains its absence.

10.3 Emulator Exits with Code 1 – Fix Summary

Cause: Using x86 image on Apple Silicon or missing HAXM on Intel.
Solution: Delete AVD ==> Create new with correct architecture OR install HAXM via SDK Manager.

11. Troubleshooting

Below are eight errors new users report most often and how to fix them.

#	Error Message (short)	Cause	Solution
1	zsh: command not found: flutter	PATH not set	Add export line to .zshrc, source it, reopen Terminal
2	Gem::FilePermissionError installing CocoaPods	Using system Ruby	Use rbenv Ruby >= 3.1, ensure which ruby points to /opt/homebrew/...
3	cmdline-tools component is missing	SDK Tools unchecked	Preferences ==> Android SDK ==> SDK Tools ==> check & install
4	Emulator exits code 1	Wrong ABI or GPU renderer	Use arm64 image on M‑series, Software graphics, reinstall AVD
5	Android license status unknown	Licenses not accepted	Run flutter doctor --android-licenses
6	Only Hello, World! prints	Wrong run configuration	Select my_first_app (main.dart) config and run again
7	adb devices shows empty list	ADB server hung	adb kill-server && adb start-server, or add platform‑tools to PATH
8	Xcode multiple matching destinations warning	macOS build arch confusion	Safe to ignore; Xcode picks arm64 by default

12. Running Your First App & Hot Reload

1. Launch the AVD you created.
2. In Android Studio, open lib/main.dart.
3. Choose your emulator from the device dropdown.
4. Click the green Run button.
5. After build completes, the default counter app appears.
6. Change 0 to a button label, save file—hot reload refreshes UI instantly.

Tip for speed: press r in the Terminal where flutter run is executing to trigger hot reload.

13. Quick‑Start Checklist

1. brew install --cask flutter (optional snapshot installer).
2. Export Flutter to PATH.
3. brew install rbenv ruby-build ==> rbenv install 3.2.2.
4. gem install cocoapods.
5. Install Android Studio, Flutter & Dart plugins.
6. SDK Manager ==> install Command‑line tools & platform 34.
7. Device Manager ==> AVD arm64 (Apple Silicon) or x86 (Intel).
8. flutter doctor --android-licenses ==> accept.
9. Create project ==> run on emulator.

Stick this list on your desk; it reduces setup to approx 30 minutes next time.

14. FAQ

Q1. Can I use VS Code instead of Android Studio?
Yes. Install Flutter & Dart extensions in VS Code and keep Android SDK via command‑line tools.

Q2. Do I need Xcode if I only target Android?
No, but flutter doctor will always warn about missing iOS toolchain. It’s safe to ignore.

Q3. Emulator feels slow — any fix?
Allocate more RAM (2–3 GB) in AVD settings and choose Cold Boot only on first launch.

Q4. Is Kotlin mandatory?
Java works but Kotlin offers null‑safety, concise interop, and is recommended by Google.

Q5. How do I update Flutter later?
Run flutter upgrade in Terminal. Then reopen Android Studio.

Congratulations

You now have a rock‑solid Flutter development environment on macOS and the knowledge to troubleshoot 90% of first‑time errors. Share this his guide on Study Warehouse with your fellow devs so they can skip the headaches you just conquered.