Start building Flutter iOS apps on macOS

To install Flutter, download the Flutter SDK bundle from its archive, move the bundle to where you want it stored, then extract the SDK.

1. 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/.

2. Create a folder where you can install Flutter.

   Consider creating a directory at ~/development/.

3. 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.

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.

1. Launch your preferred text editor.

2. If it exists, open the Zsh environmental variable file ~/.zshenv in your text editor. If it doesn't, create ~/.zshenv.

3. Copy the following line and paste it at the end of your ~/.zshenv file.

   bash

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

4. Save your ~/.zshenv file.

5. To apply this change, restart all open terminal sessions.

If you use another shell, check out this tutorial on setting your PATH.

To deploy your Flutter app to a physical iPhone or iPad, you need to do the following:

• Create an Apple Developer account.
• Set up physical device deployment in Xcode.
• Create a development provisioning profile to self-sign certificates.
• Install the third-party CocoaPods dependency manager if your app uses Flutter plugins.

You can skip this step for now. You don't actually need an Apple Developer account until you are ready to distribute your app to the App Store.

If you only need to test deploying your app, complete the first step and move on to the next section.

1. If you don't have an Apple ID, create one.

2. If you haven't enrolled in the Apple Developer program, enroll now.

   To learn more about membership types, check out Choosing a Membership.

Configure your physical iOS device to connect to Xcode.

1. Attach your iOS device to the USB port on your Mac.

2. On first connecting your iOS device to your Mac, your iOS device displays the Trust this computer? dialog.

3. Click Trust.

   

4. When prompted, unlock your iOS device.

Starting with iOS 16, Apple requires you to enable Developer Mode to protect against malicious software. Enable Developer Mode before deploying to a device running iOS 16 or later.

1. Tap on Settings > Privacy & Security > Developer Mode.

2. Tap to toggle Developer Mode to On.

3. Tap Restart.

4. After the iOS device restarts, unlock your iOS device.

5. When the Turn on Developer Mode? dialog appears, tap Turn On.

   The dialog explains that Developer Mode requires reducing the security of the iOS device.

6. Unlock your iOS device.

To deploy to a physical iOS device, you need to establish trust with your Mac and the iOS device. This requires you to load signed developer certificates to your iOS device. To sign an app in Xcode, you need to create a development provisioning profile.

To provision your project, follow the Xcode signing flow.

1. Launch Xcode.

2. Go to Xcode > Settings...

   1. Go to Xcode > Settings...
   2. Click Accounts.
   3. Click +.
   4. Select Apple ID and click Continue.
   5. When prompted, enter your Apple ID and Password.
   6. Close the Settings dialog.

   Development and testing supports any Apple ID.

3. Go to File > Open...

   You can also press Cmd + O.

4. Navigate to your Flutter project directory.

5. Open the default Xcode workspace in your project: ios/Runner.xcworkspace.

6. Select the physical iOS device you intend to deploy to in the device drop-down menu to the right of the run button.

   It should appear under the iOS devices heading.

7. In the left navigation panel under Targets, select Runner.

8. In the Runner settings pane, click Signing & Capabilities.

9. Select All at the top.

10. Select Automatically manage signing.

11. Select a team from the Team dropdown menu.

    Teams are created in the App Store Connect section of your Apple Developer Account page. If you have not created a team, you can choose a personal team.

    The Team dropdown displays that option as Your Name (Personal Team).

    

    After you select a team, Xcode performs the following tasks:

    1. Creates and downloads a Development Certificate
    2. Registers your device with your account,
    3. Creates and downloads a provisioning profile if needed

If automatic signing fails in Xcode, verify that the project's General > Identity > Bundle Identifier value is unique.

When you attach your physical iOS device for the first time, enable trust for both your Mac and the Development Certificate on the iOS device.

You should have enabled trust of your Mac on your iOS device when you attached the device to your Mac.

Enabling certificates varies in different versions of iOS.

If the codesign wants to access key... dialog displays:

1. Enter your macOS password.

2. Tap Always Allow.

To debug your device using a Wi-Fi connection, follow this procedure.

1. Connect your iOS device to the same network as your macOS device.

2. Set a passcode for your iOS device.

3. Open Xcode.

4. Go to Window > Devices and Simulators.

   You can also press Shift + Cmd + 2.

5. Select your iOS device.

6. Select Connect via Network.

7. Once the network icon appears next to the device name, unplug your iOS device from your Mac.

If you don't see your device listed when using flutter run, extend the timeout. The timeout defaults to 10 seconds. To extend the timeout, change the value to an integer greater than 10.

flutter run --device-timeout 60