Skip to main content

Mobile development · Beginner · 18 min

How to Install Flutter 3.50 and Run Your First App

By Padding · Updated 15 Nov 2026
Flutter 3.50 · Dart 3.14

You will install the Flutter 3.50 SDK on macOS or Linux, check your setup with flutter doctor, create an app, run it in a browser or on a device, change it with hot reload, replace the counter with your own screen, and write a widget test.

On this page

Flutter is Google's toolkit for building apps for iOS, Android, the web and the desktop from one codebase, written in the Dart language. Instead of wrapping native buttons, Flutter draws every pixel itself, so an app looks the same everywhere and reacts quickly. Everything on the screen is a widget, and a widget is a small piece of Dart that describes part of the interface.

The commands and the Dart code in this tutorial follow the Flutter documentation. They were not run for this page, so the outputs described are what the documentation leads you to expect. This tutorial installs the current stable release, Flutter 3.50 with Dart 3.14, and takes you from an empty folder to a running app that you change and test. The manual install shown here works on macOS and Linux and gives you the same SDK as any other method. On Windows, follow the Windows tab of the same Flutter installation page and continue from the step "Create an app". The commands that follow it are the same on every system.

Step 1 · Install the prerequisites

On macOS, Flutter needs Git, which comes with the Xcode command-line tools. If you do not have Git yet, install the tools:

Bash
xcode-select --install

On Ubuntu and other Debian-based Linux systems, install the packages the Flutter documentation lists:

Bash
sudo apt-get update -y
sudo apt-get install -y curl git unzip xz-utils zip libglu1-mesa

Step 2 · Download and unpack the SDK

Download the stable bundle for your system from the Flutter installation page (docs.flutter.dev/install/manual). Flutter 3.50.0 is named flutter_macos_3.50.0-stable.zip for macOS (choose the Apple silicon or Intel download that matches your Mac; the documentation notes that Flutter is deprecating support for Intel Macs and that future releases will require Apple silicon) and flutter_linux_3.50.0-stable.tar.xz for Linux. The Linux archive is for x86-64 processors only. The Flutter team also publishes a SHA-256 checksum for each release in its release index, so you can compare it with shasum -a 256 <file> on macOS or sha256sum <file> on Linux.

Unpack it into a folder whose path has no spaces and needs no administrator rights. The documentation suggests ~/develop:

Bash
mkdir -p ~/develop
unzip ~/Downloads/flutter_macos_3.50.0-stable.zip -d ~/develop/

On Linux, extract the tarball instead:

Bash
mkdir -p ~/develop
tar -xf ~/Downloads/flutter_linux_3.50.0-stable.tar.xz -C ~/develop/

Both create the folder ~/develop/flutter. A hand-installed SDK gets no updates from your system's package manager. You update it yourself with flutter upgrade, which moves you to the newest stable release.

Step 3 · Add Flutter to your PATH

Add the SDK's bin folder to your PATH so the flutter and dart commands work in any folder. On macOS with the default Zsh, append to ~/.zprofile. The line goes in once, so run it once:

Bash
echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> ~/.zprofile

On Linux with Bash, append it to ~/.bashrc, and with Zsh to ~/.zshenv:

Bash
echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> ~/.bashrc

Close the terminal and open a new one so that the change takes effect.

Check it worked

Bash
flutter --version
dart --version

flutter --version should print Flutter 3.50.0 on the stable channel, and dart --version should report Dart 3.14.0. The first run of flutter downloads the Dart SDK and some tools, so it takes a minute.

Step 4 · Run flutter doctor

flutter doctor inspects your computer and reports what is missing for each target platform:

Bash
flutter doctor

You need a check mark ([✓]) for Flutter itself, and for each platform you plan to use. A warning ([!]) or cross ([✗]) for a platform you do not use yet, such as Android Studio when you only want the web, can wait. Typical fixes:

  • For iOS, install Xcode from the Mac App Store, open it once to accept the licence, and run sudo xcodebuild -runFirstLaunch. iOS development works on macOS only.
  • For Android, install Android Studio, open it, and let it install the Android SDK. Then run flutter doctor --android-licenses and accept the licences.
  • For the web, install Google Chrome. Flutter finds it by itself.
  • flutter doctor -v gives details about each item.

Step 5 · Create an app

Bash
mkdir -p ~/flutter-demo
cd ~/flutter-demo
flutter create hello_flutter
cd hello_flutter

flutter create makes a complete starter project and downloads its packages. The names with underscores are required by Dart for a project name. Three parts matter now:

  • lib/main.dart holds the app. lib is where your Dart code lives.
  • pubspec.yaml lists the project's name, its Dart version range and its dependencies. flutter pub add <package> adds a dependency to it.
  • test/widget_test.dart is a starter test. You replace it later.

android, ios, web and other folders hold the platform wrappers. You rarely edit them at the start.

Step 6 · Run it

List the places you can run the app on:

Bash
flutter devices

You see devices such as Chrome, and a macOS or Linux desktop entry, and any simulator, emulator or connected phone that is running. Start the app on one of them. The browser is the quickest because it needs no extra setup:

Bash
flutter run -d chrome

On a phone or an emulator, use the device ID from flutter devices after -d, or run flutter run and pick from the list. The first run compiles the app and takes a few minutes. The app then opens with the starter screen.

Leave the app running in the terminal. While it runs, these keys work in that terminal: r applies your edits with hot reload, R restarts the app and resets its state, q quits, and h shows the full list.

Step 7 · Change the app with hot reload

Replace lib/main.dart with your own small app. It keeps a list of reminders and lets you add and tick them, using only widgets that ship with Flutter:

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

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Reminders',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo),
      ),
      home: const RemindersPage(),
    );
  }
}

class RemindersPage extends StatefulWidget {
  const RemindersPage({super.key});

  @override
  State<RemindersPage> createState() => _RemindersPageState();
}

class _RemindersPageState extends State<RemindersPage> {
  final List<({String title, bool done})> _items = [
    (title: 'Install Flutter', done: true),
    (title: 'Run the first app', done: false),
  ];
  final TextEditingController _controller = TextEditingController();

  void _add() {
    final title = _controller.text.trim();
    if (title.isEmpty) return;
    setState(() {
      _items.add((title: title, done: false));
      _controller.clear();
    });
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Reminders')),
      body: Column(
        children: [
          Padding(
            padding: const EdgeInsets.all(16),
            child: Row(
              children: [
                Expanded(
                  child: TextField(
                    controller: _controller,
                    decoration: const InputDecoration(labelText: 'New reminder'),
                    onSubmitted: (_) => _add(),
                  ),
                ),
                const SizedBox(width: 8),
                FilledButton(onPressed: _add, child: const Text('Add')),
              ],
            ),
          ),
          Expanded(
            child: ListView.builder(
              itemCount: _items.length,
              itemBuilder: (context, index) {
                final item = _items[index];
                return CheckboxListTile(
                  title: Text(item.title),
                  value: item.done,
                  onChanged: (value) {
                    setState(() {
                      _items[index] = (title: item.title, done: value ?? false);
                    });
                  },
                );
              },
            ),
          ),
        ],
      ),
    );
  }
}

Read it in three parts. A StatelessWidget such as RemindersApp describes a piece of interface that depends only on its inputs. A StatefulWidget such as RemindersPage has a companion State object that holds data that changes, here the list. Calling setState tells Flutter that the data changed, and it runs build again to redraw. build returns a tree of widgets: a Scaffold with an app bar, then a Column that holds the input row and the list. A ListView.builder only builds the rows that are on screen.

With the app still running, save the file and press r in the terminal. The screen should change without a restart, and the items you ticked should stay ticked. That is hot reload. Change Colors.indigo to Colors.teal, save, press r, and the colour scheme changes with it.

Check it worked

Type a reminder, press Add, and tick a box. The new row appears and the box stays ticked. Quit the app with q.

Step 8 · Test the widget

Flutter ships a test framework for widgets, and flutter test runs it with no device. Replace the starter test, which tests the counter that you removed:

Dart
import 'package:flutter_test/flutter_test.dart';
import 'package:hello_flutter/main.dart';

void main() {
  testWidgets('adds a reminder to the list', (tester) async {
    await tester.pumpWidget(const RemindersApp());

    expect(find.text('Install Flutter'), findsOneWidget);
    expect(find.text('Buy milk'), findsNothing);

    await tester.enterText(find.byType(TextField), 'Buy milk');
    await tester.tap(find.text('Add'));
    await tester.pump();

    expect(find.text('Buy milk'), findsOneWidget);
  });

  testWidgets('ignores an empty reminder', (tester) async {
    await tester.pumpWidget(const RemindersApp());
    final before = find.byType(CheckboxListTile).evaluate().length;

    await tester.tap(find.text('Add'));
    await tester.pump();

    expect(find.byType(CheckboxListTile).evaluate().length, before);
  });
}

Save it as test/widget_test.dart, which replaces the starter file. Then run the tests, and the static analyser, which finds mistakes and style problems:

Bash
flutter test
flutter analyze

flutter test should end with a message that all tests passed, and flutter analyze with No issues found!. pumpWidget builds your app inside a minimal test app, and pump redraws it after a change, which is why the test calls it after tapping. find.text and find.byType locate widgets on the fake screen.

Troubleshooting

  • flutter: command not found: the PATH change did not take effect. Open a new terminal, and check echo $PATH for develop/flutter/bin.
  • flutter doctor reports Unable to find bundled Java version or Android licences not accepted: open Android Studio once, then run flutter doctor --android-licenses.
  • An error about the Xcode command-line tools: run sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer, then sudo xcodebuild -runFirstLaunch.
  • The app builds but a package complains about the Dart version: the environment: sdk: range in pubspec.yaml must include 3.14. Run flutter pub get after you change it.
  • Hot reload does nothing for a change to main() or to a field initialiser: use hot restart with R.

Step 9 · Clean up

Delete the practice project. The SDK stays, because you will use it for the next project. To remove Flutter completely, delete ~/develop/flutter, remove the PATH line you added, and delete ~/.flutter, ~/.config/flutter and ~/.pub-cache. The next command deletes the practice folder and everything in it:

Bash
cd ~
rm -rf ~/flutter-demo

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.