Flutter Setup Guide — SDK Installation and First Project

Flutter is Google's UI toolkit for building natively compiled applications for mobile, web, and desktop from a single codebase. This guide covers SDK installation, platform setup, and creating your first Flutter project.

What Will You Learn

• Installing the Flutter SDK on Windows, macOS, and Linux
• Setting up platform-specific toolchains (Android, iOS, web)
• Configuring IDE support for VS Code and Android Studio
• Creating and running your first Flutter project
• Using Flutter doctor to verify the setup
• Running on emulators, simulators, and physical devices

Why It Matters

Flutter is the most popular cross-platform framework with over 500,000 apps published. A correct development environment setup is the foundation for productive Flutter development. Errors at this stage waste hours of debugging. This guide covers every platform and common configuration issues so you can focus on building apps instead of troubleshooting tools.

Learning Path

flowchart LR
  A[Records and Patterns] --> B[Flutter Setup\nYou are here]
  B --> C[Flutter Widgets]
  style B fill:#f90,color:#fff

Installing Flutter

Download the Flutter SDK from the official website and install it on your operating system.

Windows

Download the ZIP archive, extract to C:\flutter, and add C:\flutter\bin to your PATH environment variable. Run flutter doctor to verify:

# Extract and set PATH
$env:Path += ";C:\flutter\bin"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [EnvironmentVariableTarget]::User)

# Verify
flutter doctor

macOS

Use the ZIP archive or install via Homebrew:

# Homebrew installation
brew install --cask flutter

# Or manual installation
cd ~
curl -O https://storage.googleapis.com/flutter_infra_release/releases/stable/macos/flutter_macos_arm64_3.16.0-stable.zip
unzip flutter_macos_*.zip
echo 'export PATH="$PATH:$HOME/flutter/bin"' >> ~/.zshrc
source ~/.zshrc

Linux

Use the snap package or extract the tarball:

# Snap installation
sudo snap install flutter --classic

# Manual installation
cd ~
wget https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.16.0-stable.tar.xz
tar xf flutter_*.tar.xz
echo 'export PATH="$PATH:$HOME/flutter/bin"' >> ~/.bashrc
source ~/.bashrc

Android Studio Setup

Install Android Studio from the official website. During installation, ensure the Android SDK, Android SDK Platform-Tools, and Android SDK Build-Tools are selected:

# After installing Android Studio, accept licenses
flutter doctor --android-licenses

# Verify Android setup
flutter doctor

Create an Android Virtual Device (AVD) from the AVD Manager in Android Studio. Select a device (Pixel 6) and a system image (API 34). The emulator is used for testing Flutter apps without a physical device.

iOS Setup (macOS Only)

iOS development requires Xcode from the Mac App Store. Install Xcode and the iOS Simulator:

# Install Xcode command-line tools
xcode-select --install

# Accept the license agreement
sudo xcodebuild -license

# Install iOS Simulator
xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcrun simctl list

Launch the iOS Simulator from Xcode or via command line:

open -a Simulator

For deployment to physical iOS devices, you need an Apple Developer account (free or paid).

Web Setup

Flutter web requires Chrome for debugging. No additional setup is needed beyond Flutter SDK installation:

# Enable web support
flutter config --enable-web

# Verify web is available
flutter devices

Output should list Chrome as an available device.

Desktop Setup

Desktop support (Windows, macOS, Linux) requires platform-specific toolchains:

# Enable desktop support
flutter config --enable-macos-desktop
flutter config --enable-windows-desktop
flutter config --enable-linux-desktop

# Verify
flutter devices

On Windows, you need Visual Studio with the "Desktop development with C++" workload. On macOS, Xcode provides the required toolchain. On Linux, install GTK development headers:

sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev

VS Code Configuration

Install the Flutter extension from the VS Code marketplace. This extension includes Dart support, the Flutter widget inspector, and the Flutter run/debug configuration:

// settings.json
{
  "dart.checkForUpdates": true,
  "flutter.autoCreateProjects": true,
  "flutter.additionalArgs": ["--enable-impeller"],
  "editor.formatOnSave": true
}

Press Ctrl+Shift+P, type "Flutter: New Project", and follow the prompts to create a new Flutter project.

Creating Your First Project

Use the command line or IDE to create a project:

flutter create my_first_app
cd my_first_app

This creates a default Flutter project with a counter app. The project structure includes:

my_first_app/
├── lib/
│   └── main.dart          # Application entry point
├── test/
│   └── widget_test.dart   # Widget tests
├── android/               # Android platform files
├── ios/                   # iOS platform files
├── web/                   # Web platform files
├── pubspec.yaml           # Dependencies and metadata
└── analysis_options.yaml  # Linter configuration

Understanding the Default App

Open lib/main.dart to see the default Flutter app:

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorSchemeSeed: Colors.blue,
        useMaterial3: true,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  final String title;
  const MyHomePage({super.key, required this.title});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Text('You have pushed the button this many times:'),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headlineMedium,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        child: const Icon(Icons.add),
      ),
    );
  }
}

This counter app demonstrates: StatelessWidget vs StatefulWidget, setState for updating UI, Material Design theming, and the Scaffold layout structure.

Running the App

Run the app on your chosen platform:

# Run on connected device or emulator
flutter run

# Run on specific platform
flutter run -d chrome        # Web
flutter run -d macos         # macOS desktop
flutter run -d windows       # Windows desktop

# Run in release mode
flutter run --release

# Run with profile mode (performance testing)
flutter run --profile

The app compiles and launches. The counter app displays a button that increments a number. During development, hot reload (type r in the terminal or save the file) applies changes in under a second.

Using Hot Reload and Hot Restart

Hot reload injects source code changes into the running Dart VM. It preserves the app state, so you can modify the UI and see changes immediately:

// While the app is running, change this line:
Text('You have pushed the button this many times:'),
// To:
Text('Button pressed count:'),

// Press 'r' in the terminal or save the file

The UI updates instantly without restarting the app. Hot restart (Shift+R) restarts the app entirely, clearing state but loading all changes.

Flutter Doctor

Run flutter doctor to diagnose any issues with your setup:

flutter doctor -v

Output should show all checkmarks. Common issues and fixes:

[✓] Flutter (Channel stable, 3.16.0)
[✓] Android toolchain (Android SDK 34)
[✓] Xcode (15.0)
[✓] Chrome (web)
[✓] Android Studio (2023.1)
[✓] VS Code (1.85)
[✓] Connected device (2 available)

If any items show [!] or [✗], the output includes instructions for fixing the issue.

Common Mistakes

1. Not adding Flutter to PATH: The flutter command is not recognized. Add the flutter/bin directory to your PATH environment variable and restart the terminal.

2. Missing Android SDK or licenses: Android Studio must be installed with the Android SDK. Run flutter doctor --android-licenses to accept all license agreements.

3. Running on iOS without Xcode: iOS development requires macOS with Xcode installed. You cannot develop iOS apps on Windows or Linux.

4. Not accepting Android licenses: Running flutter doctor shows Android license issues. Run flutter doctor --android-licenses and type y for each license.

5. Using an outdated Flutter version: Run flutter upgrade to get the latest stable version. Outdated versions may have bugs or missing features.

Practice Questions

1. What does flutter doctor check and why is it important?
2. How does hot reload differ from hot restart?
3. What platform-specific toolchains are needed for each Flutter target?
4. Why does iOS development require macOS?
5. Challenge: Create a new Flutter project, modify the default counter app to decrement on a long press, run it on two different platforms (e.g., web and Android emulator), and verify hot reload works.

Mini Project

Create a Flutter project that demonstrates the development environment works:

• Create a new project with flutter create environment_test
• Modify the app to display the current platform (Android/iOS/web/desktop)
• Add a button that prints "Hello from Flutter" to the console
• Verify hot reload works by changing text without restarting
• Run on at least two platforms

FAQ

What is Next

Now that Flutter is installed, learn the core concept of widgets. Proceed to Flutter Widgets for understanding the widget tree and building UI. Then explore Flutter Layout for arranging widgets on screen.