Environment setup

Installing the Flutter 3.44 SDK, wiring up an editor, satisfying the Android and iOS toolchains, and getting a first app running. Examples use Windows paths where the OS matters; the Flutter commands themselves are identical everywhere.

Contents

• Install the SDK
• Managing SDK versions with FVM
• Editors
• Android toolchain
• iOS and macOS toolchain
• Create and run a project
• Everyday commands
• Troubleshooting

Install the SDK

Download the stable SDK archive from the official Flutter site and extract it to a path with no spaces and no special characters. On Windows, avoid C:\Program Files — the SDK writes into its own directory and needs write access.

C:\src\flutter          good
C:\Program Files\flutter  bad — permissions and the space both cause trouble

Add the bin directory to PATH:

# Opens the environment variables editor
rundll32 sysdm.cpl,EditEnvironmentVariables
# Add: C:\src\flutter\bin

Verify in a new terminal, then run the doctor:

flutter --version
flutter doctor -v

flutter doctor is the source of truth for what is still missing. Work down its list until everything you need is a checkmark; the web and desktop entries can stay unresolved if you are not targeting those platforms.

Record the exact version your project builds against — the output of flutter --version pins the framework, the engine revision, and the bundled Dart release.

Managing SDK versions with FVM

One global SDK stops working as soon as two projects need different Flutter versions. FVM installs SDKs side by side and pins one per project.

dart pub global activate fvm

fvm install 3.44.0          # install a specific SDK
fvm use 3.44.0              # pin it for the current project
fvm list                    # what is installed

fvm flutter run             # run through the pinned SDK
fvm dart --version

fvm use writes .fvmrc and creates .fvm/ in the project. Commit the pin file so the team and CI resolve the same SDK; add the cache directory to .gitignore. Point your editor's Flutter SDK setting at the project's .fvm/flutter_sdk symlink so analysis matches the build.

Editors

VS Code — install the Flutter extension (it pulls in Dart). Useful commands from the palette:

Command	Use
Flutter: New Project	Scaffold an app, package, or plugin
Flutter: Select Device	Pick the target emulator or device
Dart: Open DevTools	Launch the profiler and inspector
Flutter: Run Flutter Doctor	Doctor output inside the editor

Enable format-on-save so dart format runs automatically — it removes an entire class of review comment. See VS Code and Tools.

Android Studio / IntelliJ — install the Flutter and Dart plugins. It is worth having Android Studio installed even if you write code in VS Code, because it owns the Android SDK, the emulator images, and the device manager. See IDE.

Android toolchain

1. Install Android Studio; it brings the SDK, platform tools, and an emulator.
2. In SDK Manager, install the SDK platform Flutter 3.44 targets plus Android SDK Command-line Tools — the licence step fails without it.
3. Accept the licences:

flutter doctor --android-licenses

4. Create a virtual device in Device Manager, or plug in a phone with USB debugging enabled.

The Android build runs Gradle, so Gradle problems surface as Flutter build failures — see Gradle. Two recurring ones:

• JDK mismatch. The Android Gradle Plugin requires a specific JDK range. Check what Flutter is using with flutter doctor -v, and set it explicitly if needed: flutter config --jdk-dir "C:\Program Files\Java\jdk-17".
• Gradle downloads on first build. The first flutter run on Android can take several minutes while Gradle fetches its distribution and dependencies.

iOS and macOS toolchain

Only on macOS:

xcode-select --install                     # command line tools
sudo xcodebuild -runFirstLaunch
sudo xcodebuild -license accept

sudo gem install cocoapods                 # or: brew install cocoapods

Open ios/Runner.xcworkspace in Xcode once to set the team and bundle identifier. Running on a physical iPhone requires a signing identity even for debug builds — see Build and release.

Create and run a project

flutter create --org com.rojarsmith --platforms=android,ios my_app
cd my_app
flutter run

--org sets the package/bundle prefix and is painful to change later, so get it right at creation. --platforms avoids generating desktop and web folders you do not intend to maintain.

While flutter run is attached:

Key	Effect
r	Hot reload — inject changed code, keep app state
R	Hot restart — rebuild the widget tree, lose state
p	Toggle the debug paint overlay
o	Toggle platform (Android/iOS) rendering
v	Open DevTools
q	Quit

Hot reload does not re-run main(), does not re-run initState for existing State objects, and cannot apply changes to const values, enum types, or top-level generic signatures. When a change seems not to apply, hot restart before you start debugging.

Everyday commands

flutter pub get                 # resolve dependencies
flutter pub add dio             # add a dependency at its current version
flutter pub upgrade --major-versions
flutter pub outdated

flutter analyze                 # static analysis
dart format .                   # format
flutter test                    # run tests

flutter clean                   # delete build artefacts
flutter devices                 # attached devices and emulators
flutter emulators --launch <id>

flutter run --profile           # profile mode, for performance work
flutter run --release

Convention used across these notes: add packages with flutter pub add, then commit the resolved constraint that lands in pubspec.yaml and the pubspec.lock it produces. Pinning a version you copied from a blog is how you end up with a dependency that no longer resolves.

Troubleshooting

Symptom	Cause and fix
flutter not recognised	PATH not updated, or the terminal predates the change — open a new one
Doctor reports "Unable to locate Android SDK"	Set the path: flutter config --android-sdk "C:\Users\you\AppData\Local\Android\Sdk"
Android licence status unknown	Install command-line tools, then flutter doctor --android-licenses
Build fails after switching SDK versions	flutter clean, delete pubspec.lock, then flutter pub get
Pod install errors on macOS	cd ios && pod repo update && pod install
Analyzer disagrees with the build	The editor is pointed at a different SDK than FVM pinned
Emulator is extremely slow	Enable hardware acceleration, or test on a physical device — which you should be doing for performance anyway

Next: Project structure.