flutter-setting-up-on-macos

Original：🇺🇸 English

Translated

Sets up a macOS environment for Flutter development. Use when configuring a macOS machine to run, build, or deploy Flutter applications for iOS or macOS.

12installs

Sourceflutter/skills

Added on2026-03-13

NPX Install

npx skill4agent add flutter/skills flutter-setting-up-on-macos

SKILL.md Content

View Translation Comparison →

Setting Up a macOS Environment for Flutter Development

Prerequisites

Ensure the following baseline requirements are met before configuring the macOS-specific toolchain:

macOS operating system.
Flutter SDK installed and added to the system
```
PATH
```
.
Active internet connection for downloading toolchains and dependencies.

Tooling Configuration

macOS desktop development requires specific Apple toolchains to compile and debug native Swift and Objective-C code.

Xcode: Required for compiling macOS desktop applications.
CocoaPods: Required for managing native dependencies used by Flutter plugins.

Workflow: Configuring macOS Tooling

Copy and follow this checklist to configure the macOS build environment.

Install Xcode: Install the latest version of Xcode from the Mac App Store or the Apple Developer portal.
Configure Command-Line Tools: Link the Xcode command-line tools to the installed Xcode version. Run the following command in the terminal:
bash
```
sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'
```
Conditional: If Xcode is installed in a custom directory, replace
```
/Applications/Xcode.app
```
with the correct absolute path.
Accept Xcode Licenses: Accept the required developer licenses by running:
bash
```
sudo xcodebuild -license
```
Read and agree to the prompts.
Install CocoaPods: Install CocoaPods to handle native macOS plugin dependencies.
bash
```
sudo gem install cocoapods
```
Conditional: If CocoaPods is already installed, ensure it is updated to the latest version (
```
sudo gem update cocoapods
```
).

Workflow: Validating the Environment

Execute this feedback loop to ensure the environment is correctly configured for macOS desktop development.

Run Validator: Execute the Flutter diagnostic tool with verbose output:
bash
```
flutter doctor -v
```
Review Errors: Check the
```
Xcode
```
section in the output.
Fix & Retry: If errors or missing components are reported under the Xcode section, resolve them according to the output instructions, then re-run
```
flutter doctor -v
```
until the Xcode section passes.
Verify Device Availability: Confirm that Flutter recognizes the macOS desktop as a valid deployment target:
bash
```
flutter devices
```
Success Criteria: The output must contain at least one entry with
```
macos
```
listed as the platform.

Troubleshooting

If the validation workflow fails, apply the following resolutions:

Missing Command-Line Tools: If
```
flutter doctor
```
reports missing tools, ensure the
```
xcode-select
```
command was run with
```
sudo
```
and points to the correct
```
.app
```
directory.
CocoaPods Not Found: If CocoaPods is installed but not detected, verify that your Ruby
```
gem
```
binary path is included in your shell's
```
PATH
```
environment variable.
Device Not Listed: If
```
flutter devices
```
does not list
```
macos
```
, ensure desktop support is enabled in your Flutter configuration:
bash
```
flutter config --enable-macos-desktop
```