Flutter Setup & First App

Running on Emulators & Physical Devices

50 min Lesson 8 of 12

Overview of Running Flutter Apps

Flutter apps can run on a wide variety of devices and platforms. Whether you are testing on an Android emulator, iOS simulator, a physical phone, or even a web browser, Flutter provides a unified development experience. In this lesson, we will cover how to set up and use each target device for running your Flutter applications.

Note: While Flutter supports Android, iOS, web, macOS, Windows, and Linux, this lesson focuses on the most common development targets: Android emulators, iOS simulators, physical Android and iOS devices, and Chrome for web testing.

Android Emulator Setup

The Android emulator allows you to test your Flutter apps on virtual Android devices without needing a physical phone. It is managed through the Android Virtual Device (AVD) Manager.

Opening AVD Manager

Accessing AVD Manager

# From Android Studio:
# Tools > Device Manager (or AVD Manager in older versions)

# From command line:
# Navigate to Android SDK tools
\$ANDROID_HOME/emulator/emulator -list-avds

# Or use the sdkmanager to install system images first
sdkmanager "system-images;android-34;google_apis;x86_64"

Creating a Virtual Device

To create a new Android Virtual Device:

Open AVD Manager and click Create Virtual Device
Choose a device profile (e.g., Pixel 7, Pixel 8 Pro, or a tablet profile)
Select a system image -- recommended: the latest stable API level with Google APIs
Configure AVD settings: name, orientation, RAM, and storage
Click Finish to create the device

Recommended System Images

# For best performance, choose system images that match your CPU:
# - Intel CPU: x86_64 images with Intel HAXM
# - AMD CPU: x86_64 images with AMD Hypervisor
# - Apple Silicon (M1/M2/M3): arm64-v8a images

# Recommended API levels (as of 2024):
# - API 34 (Android 14) -- Latest stable
# - API 33 (Android 13) -- Wide compatibility
# - API 30 (Android 11) -- Minimum recommended for testing

# Always choose "Google APIs" variants for Google services support

Launching the Emulator

Starting an Android Emulator

# From command line
emulator -avd Pixel_7_API_34

# List available AVDs
emulator -list-avds

# Launch with specific options
emulator -avd Pixel_7_API_34 -no-snapshot -wipe-data

# Cold boot (fresh start)
emulator -avd Pixel_7_API_34 -no-snapshot-load

# From Android Studio: Click the play button next to the AVD
# From VS Code: Select the device from the bottom status bar

Tip: Enable hardware acceleration for much better emulator performance. On macOS with Apple Silicon, this is automatic. On Intel Macs, install Intel HAXM. On Windows, enable either Intel HAXM or Windows Hypervisor Platform (WHPX). On Linux, use KVM.

iOS Simulator Setup

The iOS simulator is available only on macOS and requires Xcode. It simulates iPhone and iPad devices for testing your Flutter apps without a physical Apple device.

Installing and Opening the Simulator

iOS Simulator Commands

# Open the iOS Simulator from command line
open -a Simulator

# Or from Xcode:
# Xcode > Open Developer Tool > Simulator

# List available simulators
xcrun simctl list devices

# Boot a specific simulator
xcrun simctl boot "iPhone 15 Pro"

# Open the Simulator app after booting
open -a Simulator

# Shutdown a simulator
xcrun simctl shutdown "iPhone 15 Pro"

# Erase all content and settings
xcrun simctl erase "iPhone 15 Pro"

Managing Simulator Devices

Creating and Managing Simulators

# List available device types and runtimes
xcrun simctl list devicetypes
xcrun simctl list runtimes

# Create a new simulator
xcrun simctl create "My iPhone 15" \
  "com.apple.CoreSimulator.SimDeviceType.iPhone-15" \
  "com.apple.CoreSimulator.SimRuntime.iOS-17-2"

# Delete a simulator
xcrun simctl delete "My iPhone 15"

# Take a screenshot of the simulator
xcrun simctl io booted screenshot ~/Desktop/screenshot.png

# Record video from the simulator
xcrun simctl io booted recordVideo ~/Desktop/video.mp4

Note: The iOS Simulator runs actual iOS frameworks but on your Mac’s CPU architecture. It is not a true emulator (it does not emulate ARM hardware) which makes it significantly faster than the Android emulator. However, it cannot test hardware-specific features like the camera, NFC, or Bluetooth.

Connecting a Physical Android Device

Testing on a physical device gives you the most accurate representation of your app’s performance and behavior. Here’s how to connect an Android device for development.

USB Debugging Setup

Enabling USB Debugging on Android

# Step 1: Enable Developer Options
# Go to: Settings > About Phone > Tap "Build Number" 7 times
# You will see: "You are now a developer!"

# Step 2: Enable USB Debugging
# Go to: Settings > Developer Options > Enable "USB Debugging"

# Step 3: Connect via USB cable
# Use a USB cable that supports data transfer (not charge-only)

# Step 4: Trust the computer
# A dialog will appear on the phone: "Allow USB debugging?"
# Check "Always allow from this computer" and tap "Allow"

# Step 5: Verify connection
flutter devices
# Should show your device like:
# SM G991B (mobile) - android-arm64 - Android 13 (API 33)

Wireless Debugging (Android 11+)

Setting Up Wireless Debugging

# Wireless debugging requires Android 11 (API 30) or higher

# Step 1: Connect phone and computer to the same Wi-Fi network

# Step 2: Enable Wireless Debugging
# Settings > Developer Options > Enable "Wireless debugging"

# Step 3: Pair the device (first time only)
# On phone: Wireless debugging > Pair device with pairing code
# Note the IP address, port, and pairing code

# Step 4: Pair from computer
adb pair 192.168.1.100:37123
# Enter the pairing code when prompted

# Step 5: Connect
adb connect 192.168.1.100:41567

# Step 6: Verify
flutter devices
# Your device should appear in the list

# To disconnect
adb disconnect 192.168.1.100:41567

Warning: Wireless debugging opens a network port on your device. Only use it on trusted networks. Disable wireless debugging when you are not actively developing, especially on public Wi-Fi networks.

Connecting a Physical iOS Device

Running Flutter apps on a physical iOS device requires an Apple Developer account and proper provisioning. The setup is more involved than Android but Flutter and Xcode handle most of the complexity.

Prerequisites

A Mac with Xcode installed
An Apple ID (free accounts work for development testing)
A USB cable (Lightning or USB-C depending on your iPhone model)
The device must be running a supported iOS version

Setting Up Your Device

iOS Device Setup Steps

# Step 1: Connect iPhone to Mac via USB cable

# Step 2: Trust the computer
# On iPhone: Tap "Trust" when prompted "Trust This Computer?"

# Step 3: Open Xcode and configure signing
# Open your Flutter project’s iOS workspace:
open ios/Runner.xcworkspace

# In Xcode:
# 1. Select "Runner" in the project navigator
# 2. Go to "Signing & Capabilities" tab
# 3. Check "Automatically manage signing"
# 4. Select your Team (your Apple ID)
# 5. Xcode generates a provisioning profile

# Step 4: First-time trust on device
# On iPhone: Settings > General > VPN & Device Management
# Find your developer profile and tap "Trust"

# Step 5: Verify
flutter devices
# Should show your iPhone

Note: With a free Apple ID, apps installed on a physical device expire after 7 days and you can only have 3 active apps at a time. A paid Apple Developer Program membership (\$99/year) removes these limitations and allows App Store distribution.

The flutter devices Command

The flutter devices command lists all available devices that Flutter can deploy to. It is the first command you should run when troubleshooting device connection issues.

Using flutter devices

# List all connected devices
flutter devices

# Example output:
# 3 connected devices:
#
# SM G991B (mobile)        - android-arm64  - Android 13 (API 33)
# iPhone 15 Pro (mobile)   - ios            - iOS 17.2 (simulator)
# Chrome (web)             - web-javascript - Google Chrome 120.0
# macOS (desktop)          - darwin-arm64   - macOS 14.2

# Show more details
flutter devices -v

# List only devices of a specific platform
flutter devices --device-id android
flutter devices --device-id ios

Running on Specific Devices with flutter run -d

The -d flag lets you specify which device to run your app on. This is essential when multiple devices are connected.

Targeting Specific Devices

# Run on a specific device by name or ID
flutter run -d "SM G991B"
flutter run -d emulator-5554
flutter run -d "iPhone 15 Pro"

# Run on Chrome (web)
flutter run -d chrome

# Run on macOS desktop
flutter run -d macos

# Run on the first available device
flutter run

# Run in release mode (optimized, no debugging)
flutter run -d chrome --release

# Run in profile mode (for performance testing)
flutter run -d emulator-5554 --profile

# Run with a specific entry point
flutter run -d chrome --target lib/main_dev.dart

# Specify a device by partial match
flutter run -d pixel    # Matches "Pixel 7"
flutter run -d chrome   # Matches "Chrome"
flutter run -d iphone   # Matches "iPhone 15 Pro"

Tip: You can use partial device names with the -d flag. Flutter will match the first device whose name contains the string you provide. For example, flutter run -d chrome will match the Chrome browser.

Running on Chrome (Web)

Flutter supports web as a target platform, allowing you to run and test your app in a web browser. This is great for quick testing and for building web applications.

Web Development Commands

# Make sure web support is enabled
flutter config --enable-web

# Run on Chrome
flutter run -d chrome

# Run on Chrome with a specific port
flutter run -d chrome --web-port 8080

# Run with web renderer options
flutter run -d chrome --web-renderer html      # HTML renderer
flutter run -d chrome --web-renderer canvaskit  # CanvasKit (default)

# Build for web deployment
flutter build web

# Build with specific renderer
flutter build web --web-renderer canvaskit

# The built files are in build/web/

Note: Flutter web supports two renderers: HTML (lighter, better for text-heavy apps) and CanvasKit (more consistent rendering, better for complex UIs). CanvasKit is the default as it provides pixel-perfect rendering across browsers, but it has a larger initial download size.

Troubleshooting Connection Issues

Device connection problems are common. Here is a systematic approach to diagnosing and fixing them.

General Troubleshooting

Diagnostic Commands

# Run Flutter doctor to check overall setup
flutter doctor -v

# Check ADB for Android devices
adb devices

# Kill and restart ADB server (fixes many Android issues)
adb kill-server
adb start-server

# Check Xcode tools for iOS
xcode-select --print-path
sudo xcode-select --switch /Applications/Xcode.app

# Clean the Flutter project
flutter clean
flutter pub get

# Check for Flutter upgrades
flutter upgrade

Common Android Issues

Android Troubleshooting

# Issue: Device not recognized
# Fix 1: Try a different USB cable (data cable, not charge-only)
# Fix 2: Try a different USB port
# Fix 3: Revoke USB debugging authorizations and re-authorize
#   Settings > Developer Options > Revoke USB debugging authorizations

# Issue: "Device unauthorized"
adb kill-server
adb start-server
# Then re-authorize on the device

# Issue: Emulator won’t start
# Fix: Cold boot the emulator
emulator -avd Pixel_7_API_34 -no-snapshot-load

# Issue: Gradle build fails
cd android
./gradlew clean
cd ..
flutter clean
flutter pub get
flutter run

# Issue: License not accepted
flutter doctor --android-licenses

Common iOS Issues

iOS Troubleshooting

# Issue: "No provisioning profile"
# Fix: Open Xcode, select Runner, enable "Automatically manage signing"
open ios/Runner.xcworkspace

# Issue: "Untrusted Developer"
# On iPhone: Settings > General > VPN & Device Management
# Trust your developer profile

# Issue: CocoaPods errors
cd ios
pod deintegrate
pod install --repo-update
cd ..

# Issue: Build fails after Flutter upgrade
flutter clean
cd ios
rm -rf Pods
rm Podfile.lock
pod install
cd ..
flutter pub get
flutter run

# Issue: Simulator not showing in devices
# Open Simulator manually
open -a Simulator
# Then check devices again
flutter devices

Multi-Device Testing

Flutter allows running your app on multiple devices simultaneously, which is useful for testing across different screen sizes and platforms.

Running on Multiple Devices

# Run on all connected devices
flutter run -d all

# Or run separate instances
# Terminal 1:
flutter run -d emulator-5554

# Terminal 2:
flutter run -d chrome

# Terminal 3:
flutter run -d "iPhone 15 Pro"

Tip: Running flutter run -d all is particularly useful for testing responsive layouts. You can see how your app looks on an Android phone, iPhone, and web browser all at the same time, and hot reload updates all of them simultaneously.

Device Configuration Best Practices

Follow these recommendations for an efficient development setup:

Use emulators for quick iterations: They are faster to start and do not require physical devices
Test on physical devices before release: Emulators cannot replicate real-world performance, touch interactions, and hardware-specific behavior
Keep emulator images updated: Use the latest API levels to test with the newest OS features
Test on multiple screen sizes: Create AVDs with different screen sizes (phone, tablet, foldable)
Use Chrome for rapid UI prototyping: Web builds start fastest and hot reload is most responsive
Profile on physical devices: Always measure performance on real hardware in profile mode

Summary

In this lesson you learned:

How to set up and use the Android emulator with AVD Manager
How to use the iOS Simulator with Xcode and simctl commands
Connecting a physical Android device via USB and wireless debugging
Connecting a physical iOS device with Apple Developer account and provisioning
Using flutter devices to list all available devices
Using flutter run -d to target specific devices
Running Flutter apps on Chrome for web development
Systematic troubleshooting for common connection issues on Android and iOS
Multi-device testing for responsive and cross-platform validation

Practice Exercise

Set up at least two different target devices: (1) Create an Android emulator with the latest API level using AVD Manager (or open the iOS Simulator if on macOS), (2) Run the default Flutter counter app on the emulator/simulator, (3) Enable Chrome as a web target and run the same app on Chrome, (4) Practice using flutter devices and flutter run -d to switch between targets. Bonus: If you have a physical device, connect it and run the app. Try running on all devices simultaneously with flutter run -d all.