Start building Flutter Android apps on macOS
- Verify system requirements
- Install the Flutter SDK
- Configure Android development
- Check your development setup
- Start developing Android on macOS apps with Flutter
- Manage your Flutter SDK
Verify system requirements
#To install and run Flutter, your macOS environment must meet the following hardware and software requirements.
Hardware requirements
#Your macOS Flutter development environment must meet the following minimal hardware requirements.
Requirement | Minimum | Recommended |
---|---|---|
CPU Cores | 4 | 8 |
Memory in GB | 8 | 16 |
Display resolution in pixels | WXGA (1366 x 768) | FHD (1920 x 1080) |
Free disk space in GB | 44.0 | 70.0 |
Software requirements
#To write and compile Flutter code for Android, install the following packages.
Operating system
#Flutter supports developing on macOS 11 (Big Sur) or later. This guide presumes your Mac runs the zsh
as your default shell.
To verify your shell configuration, expand this section
Like most UNIX-like operating system, macOS can support multiple shells, like bash
, zsh
, and sh
. As of the October 2019 release of macOS Catalina (macOS 10.15), Zsh or zsh
is the default shell for macOS.
Check and set zsh
as default
#To verify
zsh
was set as the default macOS shell, run the Directory Services command line utility.dscl . -read ~/ UserShell
The command should print the following as its response.
UserShell: /bin/zsh
You can skip the remaining steps.
If you need to install
zsh
, follow the procedure in this Wiki.If you need to change your default shell to
zsh
, run thechsh
command.chsh -s `which zsh`
To learn more about macOS and zsh
, check out Use zsh as the default shell on your Mac in the macOS documentation.
Some Flutter components require the Rosetta 2 translation process on Macs running Apple silicon. To run all Flutter components on Apple silicon, install Rosetta 2.
sudo softwareupdate --install-rosetta --agree-to-license
Development tools
#Download and install the following packages.
Android Studio 2023.3.1 (Jellyfish) or later to debug and compile Java or Kotlin code for Android. Flutter requires the full version of Android Studio.
Git 2.27 or later to manage source code.To check if you have
git
installed, typegit version
in your Terminal. If you need to installgit
, typebrew install git
.
The developers of the preceding software provide support for those products. To troubleshoot installation issues, consult that product's documentation.
When you run the current version of flutter doctor
, it might list a different version of one of these packages. If it does, install the version it recommends.
Text editor or integrated development environment
#You can build apps with Flutter using any text editor or integrated development environment (IDE) combined with Flutter's command-line tools.
Using an IDE with a Flutter extension or plugin provides code completion, syntax highlighting, widget editing assists, debugging, and other features.
Popular options include:
- Visual Studio Code 1.77 or later with the Flutter extension for VS Code.
- Android Studio 2023.3.1 (Jellyfish) or later with the Flutter plugin for IntelliJ.
- IntelliJ IDEA 2023.3 or later with both the Flutter plugin for IntelliJ and the Android plugin for IntelliJ.
Install the Flutter SDK
#To install the Flutter SDK, you can use the VS Code Flutter extension or download and install the Flutter bundle yourself.
Use VS Code to install Flutter
#To install Flutter using these instructions, verify that you have installed Visual Studio Code 1.77 or later and the Flutter extension for VS Code.
Prompt VS Code to install Flutter
#Launch VS Code.
To open the Command Palette, press Command + Shift + P.
In the Command Palette, type
flutter
.Select Flutter: New Project.
VS Code prompts you to locate the Flutter SDK on your computer.
If you have the Flutter SDK installed, click Locate SDK.
If you do not have the Flutter SDK installed, click Download SDK.
This option sends you the Flutter install page if you have not installed Git as directed in the development tools prerequisites.
When prompted Which Flutter template?, ignore it. Press Esc. You can create a test project after checking your development setup.
Download the Flutter SDK
#When the Select Folder for Flutter SDK dialog displays, choose where you want to install Flutter.
VS Code places you in your user profile to start. Choose a different location.
Consider
~/development/
Click Clone Flutter.
While downloading Flutter, VS Code displays this pop-up notification:
Downloading the Flutter SDK. This may take a few minutes.
This download takes a few minutes. If you suspect that the download has hung, click Cancel then start the installation again.
Once it finishes downloading Flutter, the Output panel displays.
Checking Dart SDK version... Downloading Dart SDK from the Flutter engine ... Expanding downloaded archive...
When successful, VS Code displays this pop-up notification:
Initializing the Flutter SDK. This may take a few minutes.
While initializing, the Output panel displays the following:
Building flutter tool... Running pub upgrade... Resolving dependencies... Got dependencies. Downloading Material fonts... Downloading Gradle Wrapper... Downloading package sky_engine... Downloading flutter_patched_sdk tools... Downloading flutter_patched_sdk_product tools... Downloading windows-x64 tools... Downloading windows-x64/font-subset tools...
This process also runs
flutter doctor -v
. At this point in the procedure, ignore this output. Flutter Doctor might show errors that don't apply to this quick start.When the Flutter install succeeds, VS Code displays this pop-up notification:
Do you want to add the Flutter SDK to PATH so it's accessible in external terminals?
VS Code may display a Google Analytics notice.
If you agree, click OK.
To enable
flutter
in all Terminal windows:- Close, then reopen all Terminal windows.
- Restart VS Code.
Download then install Flutter
#To install Flutter, download the Flutter SDK bundle from its archive, move the bundle to where you want it stored, then extract the SDK.
Download the following installation bundle to get the latest stable release of the Flutter SDK.
Intel Processor Apple Silicon (loading...) (loading...) For other release channels, and older builds, check out the SDK archive.
The Flutter SDK should download to the macOS default download directory:
~/Downloads/
.Create a folder where you can install Flutter.
Consider creating a directory at
~/development/
.Extract the file into the directory you want to store the Flutter SDK.
unzip ~/Downloads/flutter_sdk_v1.0.0.zip \ -d ~/development/
When finished, the Flutter SDK should be in the
~/development/flutter
directory.
Add Flutter to your PATH
#To run Flutter commands in the Terminal, add Flutter to the PATH
environment variable. This guide presumes your Mac runs the latest default shell, zsh
. Zsh uses the .zshenv
file for environment variables.
Launch your preferred text editor.
If it exists, open the Zsh environmental variable file
~/.zshenv
in your text editor. If it doesn't, create~/.zshenv
.Copy the following line and paste it at the end of your
~/.zshenv
file.bashexport PATH=$HOME/development/flutter/bin:$PATH
Save your
~/.zshenv
file.To apply this change, restart all open terminal sessions.
If you use another shell, check out this tutorial on setting your PATH.
Configure Android development
#Configure the Android toolchain in Android Studio
#To create Android apps with Flutter, verify that the following Android components have been installed.
- Android SDK Platform, API 35.0.1
- Android SDK Command-line Tools
- Android SDK Build-Tools
- Android SDK Platform-Tools
- Android Emulator
If you haven't installed these, or you don't know, continue with the following procedure.
Otherwise, you can skip to the next section.
Launch Android Studio.
The Welcome to Android Studio dialog displays.
Follow the Android Studio Setup Wizard.
Install the following components:
- Android SDK Platform, API 35.0.1
- Android SDK Command-line Tools
- Android SDK Build-Tools
- Android SDK Platform-Tools
- Android Emulator
Launch Android Studio.
Go to the Settings dialog to view the SDK Manager.
If you have a project open, go to Tools > SDK Manager.
If the Welcome to Android Studio dialog displays, click the More Options icon that follows the Open button and click SDK Manager from the dropdown menu.
Click SDK Platforms.
Verify that Android API 35.0.1 has been selected.
If the Status column displays Update available or Not installed:
Select Android API 35.0.1.
Click Apply.
When the Confirm Change dialog displays, click OK.
The SDK Quickfix Installation dialog displays with a completion meter.
When the install finishes, click Finish.
After you installed the latest SDK, the Status column might display Update available. This means some additional system images might not be installed. You can ignore this and continue.
Click SDK Tools.
Verify that the following SDK Tools have been selected:
- Android SDK Command-line Tools
- Android SDK Build-Tools
- Android SDK Platform-Tools
- Android Emulator
If the Status column for any of the preceding tools displays Update available or Not installed:
Select the needed tools.
Click Apply.
When the Confirm Change dialog displays, click OK.
The SDK Quickfix Installation dialog displays with a completion meter.
When the install finishes, click Finish.
Configure your target Android device
#Set up the Android emulator
#To configure your Flutter app to run in an Android emulator, follow these steps to create and select an emulator.
Enable VM acceleration on your development computer.
Start Android Studio.
Go to the Settings dialog to view the SDK Manager.
If you have a project open, go to Tools > Device Manager.
If the Welcome to Android Studio dialog displays, click the More Options icon that follows the Open button and click Device Manager from the dropdown menu.
Click Virtual.
Click Create Device.
The Virtual Device Configuration dialog displays.
Select either Phone or Tablet under Category.
Select a device definition. You can browse or search for the device.
Click Next.
Click x86 Images if your Mac runs on an Intel CPU or ARM Images if your Mac runs on an Apple CPU.
Click one system image for the Android version you want to emulate.
If the desired image has a Download icon to the right of the Release Name, click it.
The SDK Quickfix Installation dialog displays with a completion meter.
When the download completes, click Finish.
Click Next.
The Virtual Device Configuration displays its Verify Configuration step.
To rename the Android Virtual Device (AVD), change the value in the AVD Name box.
Click Show Advanced Settings and scroll to Emulated Performance.
From the Graphics dropdown menu, select Hardware - GLES 2.0.
This enables hardware acceleration and improves rendering performance.
Verify your AVD configuration. If it is correct, click Finish.
To learn more about AVDs, check out Managing AVDs.
In the Device Manager dialog, click the Run icon to the right of your desired AVD. The emulator starts up and displays the default canvas for your selected Android OS version and device.
Set up your target Android device
#To configure your Flutter app to run on a physical Android device, you need an Android device running Android API level 21 or later.
Enable Developer options and USB debugging on your device as described in the Android documentation.
[Optional] To leverage wireless debugging, enable Wireless debugging on your device as described in the Android documentation.
Plug your device into your macOS computer. If your device prompts you, authorize your computer to access your device.
Verify that Flutter recognizes your connected Android device.
In the Terminal, run:
flutter devices
By default, Flutter uses the version of the Android SDK where your
adb
tool is based. To use a different Android SDK installation path with Flutter, set theANDROID_SDK_ROOT
environment variable to that installation directory.
Agree to Android licenses
#Before you can use Flutter and after you install all prerequisites, agree to the licenses of the Android SDK platform.
Open an elevated console window.
Run the following command to enable signing licenses.
flutter doctor --android-licenses
If you accepted the Android Studio licenses at another time, this command returns:
[========================================] 100% Computing updates... All SDK package licenses accepted.
You can skip the next step.
Before agreeing to the terms of each license, read each with care.
Troubleshooting licensing issues
#How to fix the error of finding Java install
You might have an issue with the Android SDK locating the Java SDK.
flutter doctor --android-licenses
ERROR: JAVA_HOME is set to an invalid directory: /Applications/Android\ Studio.app/Contents/jre/Contents/Home
Please set the JAVA_HOME variable in your environment to match the
location of your Java installation.
Android sdkmanager tool was found, but failed to run
(/Users/atsansone/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager): "exited code 1".
Try re-installing or updating your Android SDK,
visit https://flutter.dev/docs/get-started/install/macos#android-setup for detailed instructions.
The flutter doctor
command returns this error because of how the JAVA_HOME
variable was set. When you add the path to JAVA_HOME
, you can add a backslash to the space between Android
and Studio
or enclose the entire path in matching quotes. You cannot do both.
Look for your JAVA_HOME
path in your appropriate shell resource file.
Change it from:
export JAVA_HOME="/Applications/Android\ Studio.app/Contents/jre/Contents/Home"
to:
export JAVA_HOME="/Applications/Android Studio.app/Contents/jre/Contents/Home"
Do not include the backslash between Android
and Studio
.
To load this updated environment variable, reload your shell. This example uses the zsh
resource file.
source ~/.zshrc
Check your development setup
#Run Flutter doctor
#The flutter doctor
command validates that all components of a complete Flutter development environment for macOS.
Open your Terminal.
To verify your installation of all the components, run the following command.
flutter doctor
As you chose to develop for Android, you do not need all components. If you followed this guide, the result of your command should resemble:
Running flutter doctor...
Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.24.0, on macOS 14.4.0 23E214 darwin-arm64, locale en)
[✓] Android toolchain - develop for Android devices (Android SDK version 35.0.1)
[!] Chrome - develop for the web
[!] Xcode - develop for iOS and macOS (Xcode not installed)
[✓] Android Studio (version 2024.1)
[✓] VS Code (version 1.92)
[✓] Connected device (1 available)
[✓] Network resources
! Doctor found issues in 2 categories.
Troubleshoot Flutter doctor issues
#When the flutter doctor
command returns an error, it could be for Flutter, VS Code, Android Studio, the connected device, or network resources.
If the flutter doctor
command returns an error for any of these components, run it again with the verbose flag.
flutter doctor -v
Check the output for other software you might need to install or further tasks to perform.
If you change the configuration of your Flutter SDK or its related components, run flutter doctor
again to verify the installation.
Start developing Android on macOS apps with Flutter
#Congratulations. Having installed all prerequisites and the Flutter SDK, you can start developing Flutter apps for Android on macOS.
To continue on your learning journey, consult the following guides:
Manage your Flutter SDK
#To learn more about managing your Flutter SDK install, consult the following resources.
- Upgrade Flutter
- Add Web debugging tools
- Add iOS simulator or device
- Add macOS compilation tools
- Uninstall Flutter
Unless stated otherwise, the documentation on this site reflects the latest stable version of Flutter. Page last updated on 2024-07-16. View source or report an issue.