How to Resolve Common Issues When You brew install flutter on macOS

Running brew install flutter often fails because the Homebrew formula lacks mandatory host dependencies like curl and unzip, and omits iOS/Android toolchain components that Flutter's bootstrap scripts and flutter doctor strictly validate.

While the official Flutter documentation recommends cloning the SDK from GitHub or downloading the archive directly, many macOS developers attempt to brew install flutter for convenience. Because the Homebrew cask is maintained outside the main flutter/flutter repository, it frequently becomes outdated or fails to include required system tools, leading to cryptic errors during the initial setup.

Why brew install flutter Fails: The Architecture Gap

Homebrew is not the primary distribution channel for Flutter. The official repository relies on its own bootstrap logic to download the Dart SDK and validate the host environment, which runs after Homebrew finishes copying files. This architectural disconnect creates three distinct failure points.

The Bootstrap Script Dependency Check

When you first run the flutter command, the bootstrap script at bin/internal/update_dart_sdk.sh executes. It explicitly checks for curl and unzip before downloading the Dart SDK. If these tools are missing, the script aborts with a specific Homebrew suggestion:

command -v curl > /dev/null 2>&1 || {
    >&2 echo 'Missing "curl" tool. Unable to download Dart SDK.'
    >&2 echo 'Consider running "brew install curl".'
    exit 1
}

Source: [bin/internal/update_dart_sdk.sh](https://github.com/flutter/flutter/blob/master/bin/internal/update_dart_sdk.sh)

Platform Tool Validation in flutter_tools

After the bootstrap completes, the Flutter tool itself validates the host OS utilities. In packages/flutter_tools/lib/src/base/os.dart, the framework checks for unzip and emits the same Homebrew hint if the binary is absent:

if (!_processManager.canRun('unzip')) {
  message = 'Consider running "brew install unzip".';
}

Source: packages/flutter_tools/lib/src/base/os.dart

Common Error Patterns and Root Causes

The following symptoms appear immediately after a brew install --cask flutter or brew install flutter command completes, each tracing back to specific validation logic in the Flutter repository.

Missing curl or unzip Errors

Homebrew installs its own dependencies in isolated prefixes, but the Flutter bootstrap script performs a global command -v check. If curl or unzip are not linked into /usr/local/bin or /opt/homebrew/bin, the script aborts with the messages found in update_dart_sdk.sh and os.dart.

Xcode and CocoaPods Not Found

The Homebrew cask does not bundle Xcode, the macOS SDK, or CocoaPods. When you run flutter doctor, the tool checks for these via the logic tested in packages/flutter_tools/test/general.shard/macos/cocoapods_test.dart. Without sudo xcodebuild -license accept and brew install cocoapods, the doctor reports critical failures.

flutter Command Not Found

The Homebrew cask installs the binary to /usr/local/Caskroom/flutter/latest/flutter/bin. Unlike formulae that symlink to /usr/local/bin, the cask requires manual PATH export. The engine/src/flutter/tools/vscode_workspace/README.md explicitly reminds developers to add installed tools to PATH, a step often missed after brew install --cask flutter.

Android SDK Detection Failures

Homebrew does not bundle Android SDK components. Flutter’s Android toolchain checks, located in packages/flutter_tools/lib/src/android/android_sdk.dart, fail if sdkmanager is absent. You must install android-platform-tools and android-sdk separately via Homebrew or Android Studio.

Step-by-Step Resolution Workflow

Follow this sequence to satisfy all bootstrap and doctor validations after installing Flutter via Homebrew.

1. Update Homebrew to ensure you have the latest cask definitions:

   brew update && brew upgrade

2. Install mandatory host tools that the bootstrap script validates:

   brew install curl unzip git

3. Install iOS and Android toolchain dependencies:

   # iOS development
   
   brew install --cask xcode
   brew install cocoapods
   
   # Android development
   
   brew install --cask android-platform-tools
   brew install --cask android-sdk
   
   # Build system utilities
   
   brew install cmake ninja pkg-config

4. Install the Flutter cask:

   brew install --cask flutter

5. Configure your PATH to include the Flutter binary. Add this to ~/.zshrc or ~/.bash_profile:

   export PATH="$PATH:/usr/local/Caskroom/flutter/latest/flutter/bin"

6. Accept the Xcode license (required for iOS builds):

   sudo xcodebuild -license accept

7. Run Flutter doctor to verify the installation:

   flutter doctor -v

   Address any remaining issues by following the specific commands suggested in the doctor output.

Automated Installation Script

For a fully automated setup, run this self-contained shell script which implements the workflow above:

#!/usr/bin/env bash
set -euo pipefail

# Update Homebrew

brew update && brew upgrade

# Install mandatory host tools (curl/unzip are critical for bin/internal/update_dart_sdk.sh)

brew install curl unzip git

# Install platform toolchains

brew install --cask xcode
brew install cocoapods
brew install --cask android-platform-tools
brew install cmake ninja pkg-config

# Install Flutter via Homebrew cask

brew install --cask flutter

# Add to PATH for current session (persist in ~/.zshrc)

export PATH="$PATH:/usr/local/Caskroom/flutter/latest/flutter/bin"

# Accept Xcode license

sudo xcodebuild -license accept

# Verify installation

flutter doctor -v

Summary

• Homebrew is not the official distribution channel for Flutter, which is why brew install flutter often misses critical dependencies required by the framework's bootstrap scripts.
• The bootstrap script at bin/internal/update_dart_sdk.sh strictly requires curl and unzip before it can download the Dart SDK, emitting specific Homebrew install suggestions if they are absent.
• Platform-specific validations in packages/flutter_tools/lib/src/base/os.dart and flutter doctor check for Xcode, CocoaPods, and Android SDK components that Homebrew does not automatically install.
• The Homebrew cask installs to /usr/local/Caskroom/flutter/latest/flutter/bin, requiring manual PATH configuration that is documented in engine/src/flutter/tools/vscode_workspace/README.md but often overlooked.
• Pre-installing curl, unzip, cocoapods, and android-platform-tools via Homebrew, then running sudo xcodebuild -license accept, resolves the majority of post-installation failures.

Frequently Asked Questions

Is brew install flutter officially supported by the Flutter team?

No. According to the Flutter repository's issue tracker documented in docs/contributing/issue_hygiene/Popular-issues.md, the team has marked Homebrew distribution as low priority. The official installation methods remain cloning the Git repository or downloading the stable archive from the Flutter website. The Homebrew formula and cask are maintained by community contributors and may lag behind official releases.

Why does flutter doctor fail immediately after a successful brew install?

flutter doctor performs validation checks that are independent of the Homebrew installation process. The tool validates host dependencies like curl and unzip via bin/internal/update_dart_sdk.sh, and platform tools via packages/flutter_tools/lib/src/base/os.dart. Because the Homebrew cask only copies the Flutter SDK without installing Xcode, CocoaPods, or the Android SDK, flutter doctor reports these as missing dependencies that you must install manually.

How do I fix the 'flutter command not found' error after installing via Homebrew?

The Homebrew cask installs Flutter to /usr/local/Caskroom/flutter/latest/flutter/bin but does not automatically symlink it to /usr/local/bin. As noted in engine/src/flutter/tools/vscode_workspace/README.md, you must manually add the installation directory to your shell's PATH. Add export PATH="$PATH:/usr/local/Caskroom/flutter/latest/flutter/bin" to your ~/.zshrc or ~/.bash_profile, then reload your shell configuration with source ~/.zshrc.

Can I use Homebrew to manage multiple Flutter versions?

No, the current Homebrew cask only supports installing the latest stable release to /usr/local/Caskroom/flutter/latest/. Unlike the manual installation method where you can clone multiple channels (stable, beta, dev) into separate directories, Homebrew manages only a single version. If you need to switch between Flutter versions for different projects, you should use the manual installation method with git checkout to switch branches, or use a version manager like fvm (Flutter Version Management) instead of Homebrew.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}