Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 73 ยท Getting started

Setting Up and Running Your First App

Install the Flutter SDK, check it with flutter doctor, create and run an app, learn hot reload versus hot restart, and tour the project folders and pubspec.yaml.

Before you write a single widget you need a working toolchain: the Flutter SDK, an editor and something to run the app on, such as an emulator or a real phone. Setup is the step where most beginners get stuck, so this lesson walks through it in order and explains what each command does and what the project it creates contains.

All commands and files in this lesson are read-only: the Flutter SDK has to be installed on your own computer, and a browser cannot run it. The one live example at the end is a JavaScript stand-in that shows the idea behind hot reload.

What you need

Your Flutter toolbox

Flutter SDK Includes Dart, the engine and the flutter command.
An editor VS Code or Android Studio with the Flutter plugin.
A target An emulator, simulator, real phone, Chrome or desktop.

The SDK already contains Dart, so there is nothing else to install for the language.

1 / 2

You can start with only the web or desktop target for your own operating system, which needs the fewest extra tools. Add Android or iOS later.

Install the SDK

Download the SDK for your system from the official Flutter site, extract it to a folder without spaces in its path (for example C:\src\flutter or ~/development/flutter), and add its bin folder to your PATH. Then open a new terminal and check that the command is found:

Terminal
flutter --version

The output lists the Flutter version, the channel (usually stable) and the Dart version bundled with it. Use the stable channel for real apps. You can switch with flutter channel stable and update with flutter upgrade.

flutter doctor

flutter doctor inspects your machine and reports what is missing. Run it after installing and after every change to your setup:

Terminal
flutter doctor

A healthy result looks something like this (versions will differ):

TEXT
Doctor summary (to see all details, run flutter doctor -v):
[โœ“] Flutter (Channel stable, 3.x.x, on Microsoft Windows)
[โœ“] Windows Version
[โœ“] Android toolchain - develop for Android devices
[โœ“] Chrome - develop for the web
[โœ“] Visual Studio - develop Windows apps
[โœ“] Android Studio
[โœ“] VS Code
[โœ“] Connected device (3 available)
[โœ“] Network resources

โ€ข No issues found!

Every [!] or [โœ—] line comes with a hint on how to fix it. Typical fixes are accepting the Android licenses with flutter doctor --android-licenses, installing the Android command-line tools, or installing Xcode. Do not skip this step: a clean doctor report saves hours of confusing build errors later.

You do not need every row to be green. If you only target Chrome and Windows, a missing Xcode is fine. Only fix what your chosen targets need.

Create and run an app

Create a project with flutter create. The name must be lowercase with underscores:

Terminal
flutter create hello_app
cd hello_app
flutter devices
flutter run
  • flutter create hello_app generates a complete, working counter app.
  • flutter devices lists every target Flutter can see (emulators, phones, Chrome, desktop).
  • flutter run builds the app and starts it on the connected device. With more than one device, add -d chrome, -d windows or a device id.

The first build can take several minutes while Gradle or Xcode downloads and compiles things. Later builds are much faster, and hot reload makes most changes instant.

Hot reload and hot restart

While flutter run is active in the terminal, two keys matter most:

Key Name What it does
r Hot reload Injects changed code into the running app and rebuilds the widgets. State is kept.
R Hot restart Restarts the app from main(). State is reset. Slower, still much faster than a full rebuild.
q Quit Stops the app.

In VS Code and Android Studio, saving a file triggers hot reload automatically.

Hot reload keeps your variables, so if you are on the third screen of the app with a counter at 7, it stays there after you change a color. That is wonderful for tweaking a design. But some changes cannot be applied that way. Changing the value that initializes a State field, editing main(), or changing an enum into a class needs a hot restart. If a change does not appear, press R before assuming something is wrong.

A full rebuild (stop and flutter run again) is needed when you change native files, add a plugin, or edit assets declared in pubspec.yaml in some cases.

A tour of the project

flutter create produces this layout:

TEXT
hello_app/
  android/          native Android project (Gradle)
  ios/              native iOS project (Xcode)
  linux/ macos/ windows/ web/   other targets
  lib/
    main.dart       the entry point of your Dart code
  test/
    widget_test.dart
  pubspec.yaml      project settings and dependencies
  analysis_options.yaml   lint rules

Almost all your work happens in lib/. The platform folders are real native projects; you touch them only for platform settings such as permissions, app icons or signing. The test/ folder holds automated tests (see Unit and Widget Testing).

The entry point is lib/main.dart. Every Dart program starts at a function called main, and a Flutter app calls runApp with its root widget:

DART
import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(
    home: Scaffold(
      body: Center(child: Text('Hello, Flutter!')),
    ),
  ));
}

pubspec.yaml

pubspec.yaml is the project's settings file: its name, version, the Dart version it supports, its dependencies and its assets.

YAML
name: hello_app
description: A first Flutter app.
publish_to: 'none'
version: 1.0.0+1

environment:
  sdk: ^3.5.0

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/images/

Key points:

  • version: 1.0.0+1 means version name 1.0.0 and build number 1. Stores need the build number to grow with every upload.
  • Indentation matters. YAML uses two spaces; tabs break the file.
  • ^1.2.0 means "1.2.0 or any compatible newer version below 2.0.0".
  • dependencies ship in your app; dev_dependencies (testing, lints) do not.

Add a package from the terminal and Flutter edits the file and downloads it for you:

Terminal
flutter pub add http
flutter pub get

Packages come from pub.dev, the public package registry for Dart and Flutter. Packages you meet later in this tutorial, such as provider and go_router, are added exactly this way.

A stand-in for hot reload

Why does hot reload keep your state? Because the state (data) and the code that builds the UI are separate things. When you reload, Flutter swaps in the new build code and runs it again against the old state. A restart throws the state away too.

JS Reload keeps state, restart resets it

Press Run (or Ctrl + Enter) to see the console output here.

No output.

After three taps the counter shows 3. Hot reload shows the new theme and still shows 3. Hot restart shows the new theme with a counter of 0. This is exactly the trade you make when you press r or R.

The second stand-in imitates what flutter doctor does: it checks a list of requirements for your chosen targets and prints the fixes for the missing ones.

JS A doctor that checks your targets

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command checks what is missing on your machine?

    flutter doctor inspects the SDK, editors, Android and iOS toolchains and prints hints for anything missing.
  2. 2. You change the initial value of a field in your State class and hot reload shows no difference. What should you do?

    Hot reload keeps existing state objects. A hot restart runs main() again and creates fresh state.
  3. 3. Where do you declare packages your app depends on?

    pubspec.yaml lists dependencies, assets and the SDK constraint. flutter pub add edits it for you.
  4. 4. In which folder do you write almost all of your Dart code?

    lib/ holds your app code, starting with main.dart. Platform folders are for native settings.

Summary

  • Install the SDK, add it to PATH, and run flutter doctor until your chosen targets are green.
  • flutter create makes a working app, flutter devices lists targets, flutter run starts it.
  • Hot reload (r) keeps state; hot restart (R) resets it; native or plugin changes need a full rebuild.
  • Your code lives in lib/, starting at main.dart; pubspec.yaml holds dependencies and assets.
  • All commands here are read-only; the TryIts are stand-ins for how reload and doctor work.

Next: Dart Basics for Flutter