How to Run a Flutter App in VS Code: A Step-by-Step Guide

Setting up a Flutter project in Visual Studio Code can feel confusing at first. Flutter may already be installed, yet the terminal cannot recognise its commands. VS Code may appear ready, but the Flutter options are missing. In other cases, the project builds successfully, but no device is available to launch it.

From working through Flutter development setups, I have found that most of these problems are not caused by the application code. They usually come from an incorrect SDK path, an incomplete Android or iOS toolchain, a missing extension, or VS Code being opened at the wrong folder level.

This guide explains how to configure Flutter in VS Code, create a project, run it on a selected device, and diagnose the setup issues developers commonly encounter.

What Do You Need to Run Flutter in VS Code?

VS Code is the editor from which you write and debug the application, but it does not contain the complete Flutter development environment.

You still need the Flutter SDK and the platform tools required by your chosen target. Android development normally requires the Android SDK, while iOS development requires Xcode and therefore a Mac. You also need a target on which the application can run, such as a physical phone, emulator, simulator, desktop, or supported web browser.

The exact requirements depend on your intended platform. You do not need to complete the iOS setup if you are developing only for Android, for example.

Prerequisites for Setting Up Flutter in VS Code

1. Install the Flutter SDK

Download the Flutter SDK by following the official Flutter installation guide for Windows, macOS, or Linux.

Extract the SDK into a permanent directory where your user account has permission to read and modify it. Avoid placing it in a temporary download folder or a protected system directory, as future upgrades may fail because of permission restrictions.

After installation, add Flutter’s bin directory to your system PATH. This allows terminals and applications such as VS Code to locate the flutter command.

Open a new terminal and verify the installation:

flutter --version

If the command is not recognised, the most likely cause is that the PATH entry is missing, incorrect, or has not been loaded into the current terminal session.

Once Flutter is detected, run:

flutter doctor -v

Flutter Doctor checks the SDK, development tools, platform toolchains, and connected devices. The verbose output also displays the paths Flutter is using, which is particularly helpful when multiple SDK installations exist.

You do not need every Flutter Doctor category to show a green check mark. Resolve the warnings associated with the platforms you intend to build for. An iOS warning does not prevent Android development on an otherwise correctly configured system.

2. Install Visual Studio Code

Download and install Visual Studio Code for your operating system.

VS Code is lightweight, but with the Flutter extension installed, it supports code completion, project creation, widget inspection, breakpoints, debugging, hot reload, and integration with Flutter DevTools.

After installing it, launch VS Code normally. If VS Code was already open while you changed the Flutter PATH, close and reopen it so the updated environment can be detected.

3. Install the Flutter Extension

Open the Extensions view in VS Code using Ctrl+Shift+X on Windows or Linux, or Cmd+Shift+X on macOS.

Search for Flutter and install the extension published by Dart Code. Installing the Flutter extension also installs the required Dart extension, so it is generally unnecessary to install Dart separately.

Validate the connection from inside VS Code:

1. Open the Command Palette with Ctrl+Shift+P or Cmd+Shift+P.
2. Search for Flutter: Run Flutter Doctor.
3. Select the command and review the output.

If Flutter commands do not appear in the Command Palette, restart VS Code and confirm that it can locate the SDK. You can also search the VS Code settings for Flutter SDK Path and provide the SDK directory manually when automatic detection fails.

The official Flutter guide for VS Code covers the current extension setup, project creation, device selection, and debugging options.

4. Set Up Android Development

Android Studio is optional as a code editor, but its SDK Manager and Device Manager provide a convenient way to install the Android SDK, platform tools, build tools, command-line tools, and emulator images required for Android development.

After installing Android Studio, open its SDK Manager and confirm that the following are available:

• An Android SDK platform
• Android SDK Platform-Tools
• Android SDK Build-Tools
• Android SDK Command-line Tools
• An emulator image if you plan to use a virtual device

Run Flutter Doctor again:

flutter doctor -v

If Flutter reports that the Android licences have not been accepted, run:

flutter doctor --android-licenses

Review and accept the licences, then run Flutter Doctor again.

To create an Android emulator, open Android Studio’s Device Manager, create a virtual device, select a suitable system image, and start the emulator. A physical Android phone can also be used by enabling Developer Options and USB debugging.

5. Set Up Xcode for iOS Development

Flutter applications can be built for iOS only on macOS. Install the latest supported version of Xcode and open it at least once so it can finish installing its required components.

Configure the Xcode command-line tools with:

sudo sh -c \
'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'

You may also need to review and accept the Xcode licence:

sudo xcodebuild -license

Start the iOS Simulator using:

open -a Simulator

For a physical iPhone, connect the device to your Mac, trust the computer, enable Developer Mode, and configure code signing through Xcode. A free personal Apple Developer account can be used for basic testing on your own device, while App Store distribution requires the appropriate programme membership.

6. Install CocoaPods When Required

CocoaPods manages native iOS and macOS dependencies used by many Flutter plugins. Install it if you plan to run an application containing plugins with native Apple-platform code.

Use the installation method recommended by the CocoaPods documentation for your environment, and then confirm the installation:

pod --version

You normally do not need to run pod install manually for every new Flutter project. Flutter’s build process handles the required dependency installation in standard cases.

If an iOS build reports missing pods or an outdated Podfile lock, navigate to the ios directory and run:

pod install

Treat this as a project-specific step or troubleshooting measure rather than a mandatory command immediately after every Flutter project is created.

7. Prepare a Target Device

A Flutter application needs an available target before it can launch. Depending on your setup, the target can be an Android emulator, iOS Simulator, physical phone, desktop platform, or web browser.

Check the available targets with:

flutter devices

A correctly detected Android emulator might appear with an Android platform label, while an iOS Simulator will appear only on a properly configured Mac.

If no mobile device is available but web support is enabled, Chrome may appear as a target. This can be useful for confirming that the basic Flutter project runs, although it does not replace testing platform-specific mobile behaviour.

How to Create a Flutter Project in VS Code

1. Create a New Project

Open the VS Code Command Palette with Ctrl+Shift+P on Windows or Linux, or Cmd+Shift+P on macOS.

Search for and select:

Flutter: New Project

Choose Application, select the parent directory in which the project should be created, and enter a project name such as:

my_flutter_app

Flutter project names should use lowercase letters and underscores rather than spaces or hyphens.

VS Code will execute the project creation process and generate the standard Flutter structure. The application’s Dart code begins in:

lib/main.dart

Its dependencies and asset declarations are managed through:

pubspec.yaml

Allow package resolution to finish before attempting to run the project.

2. Open an Existing Flutter Project Correctly

To open an existing project, select File → Open Folder and choose the project directory containing pubspec.yaml.

This folder detail is easy to overlook. If you open only the lib directory or a parent folder that does not expose the Flutter project properly to the workspace, VS Code may not recognise it as a Flutter application. The Flutter SDK version and device selector may then be missing from the status bar.

When VS Code correctly detects the project, its lower status bar should display Flutter information and the currently selected device or No Devices.

3. Fetch the Project Dependencies

New projects generally fetch their dependencies automatically. For an existing project or after changing pubspec.yaml, run:

flutter pub get

This reads the project’s dependency declarations and downloads the required packages.

If dependency resolution fails, read the version-conflict output before deleting lockfiles or changing package versions. The message normally identifies the packages whose requirements cannot be satisfied together.

How to Run a Flutter App in VS Code

1. Open the Project Root

Confirm that VS Code has opened the folder containing pubspec.yaml. The default application entry point should be available at lib/main.dart.

If VS Code cannot find the Flutter project, running and debugging commands may not appear even when Flutter is correctly installed.

2. Select a Device

Look at the device name in the lower-right area of the VS Code status bar. Click it to display the available targets and choose the device you want to use.

If the status bar shows No Devices, start an emulator or simulator, or connect a physical device. You can verify detection in the integrated terminal:

flutter devices

When several devices are connected, selecting one explicitly prevents Flutter from launching on an unintended target.

3. Run the App with Debugging

Open lib/main.dart and press F5. You can also select:

Run → Start Debugging

VS Code will build the application, install it on the selected device, start it in debug mode, and attach the debugger. The first Android or iOS build may take longer because Flutter needs to download or compile platform dependencies.

After the application launches, you can set breakpoints, inspect variables, review stack frames, and read application output from the Debug Console.

4. Run Without Breakpoints

To run without attaching the full debugger, press Ctrl+F5 or select:

Run → Start Without Debugging

This still runs a development build but avoids stopping at breakpoints.

5. Run from the Integrated Terminal

Open the VS Code terminal with Ctrl+` on Windows or Linux, or Cmd+` on macOS.

Make sure the terminal is in the project directory, then run:

flutter run

If multiple devices are available, Flutter may ask you to choose one. You can also target a device directly:

flutter run -d <device-id>

Device IDs are shown by flutter devices.

Running from the terminal is particularly useful when diagnosing failures because the complete build output is visible and easy to copy or search.

Using Hot Reload and Hot Restart

Once the app is running in debug mode, Flutter can apply many Dart code changes without rebuilding and relaunching the complete application.

Hot reload updates the interface while preserving the current application state. In a terminal session, press:

r

In VS Code, you can use the Hot Reload button in the debug toolbar or save the file when hot reload on save is enabled.

Hot restart reloads the application’s Dart code and resets its in-memory state. In the terminal, press:

R

Use hot reload for most interface and logic edits. Use hot restart when changes affect initialisation, global state, or code that hot reload cannot reconstruct. Changes to native Android or iOS files may require stopping and rebuilding the application entirely.

Troubleshooting Common Flutter and VS Code Issues

Flutter Command Not Found

If the terminal displays flutter: command not found or reports that Flutter is not recognised, the SDK’s bin directory is not available through the current PATH.

Check that the PATH points to the actual Flutter installation rather than the downloaded archive or its parent directory. Open a new terminal after changing the PATH and restart VS Code.

Run the following to verify which Flutter executable is being used:

On Windows:

where flutter

On macOS or Linux:

which flutter

This is also useful when an older Flutter installation is being detected instead of the intended SDK.

VS Code Does Not Recognise the Flutter Project

If Flutter commands, the SDK version, or the device selector are missing, confirm that the folder containing pubspec.yaml is part of the VS Code workspace.

This has been one of the most common setup mistakes in practice: the developer opens lib/ because that is where the Dart code exists, but the extension needs the complete project structure to recognise it correctly.

Restart the Dart analysis server or reopen VS Code after correcting the workspace folder.

No Devices Found

Start the Android emulator or iOS Simulator before running the project. For a physical device, confirm that it is unlocked, trusted, and correctly configured for development.

Run:

flutter devices
flutter doctor -v

For Android, also check USB debugging and accept the authorisation prompt displayed on the device. Some Windows computers require an OEM USB driver.

For iOS, verify that the device trusts the Mac, Developer Mode is enabled, and signing has been configured.

Android SDK Not Found

Open Android Studio and install the SDK through SDK Manager. If Flutter still cannot locate it, check the path shown by flutter doctor -v.

You can explicitly configure the SDK location when necessary:

flutter config --android-sdk <path-to-android-sdk>

Use the actual SDK directory for your system rather than copying a path from another computer.

Android Licences Not Accepted

Run:

flutter doctor --android-licenses

Accept the required licences and verify the result with:

flutter doctor -v

If the licence command itself fails, confirm that the Android SDK command-line tools are installed through Android Studio.

Missing Flutter Packages

When imports cannot be resolved or the project reports missing dependencies, run:

flutter pub get

If the issue remains, confirm that the dependency is correctly declared under dependencies or dev_dependencies in pubspec.yaml. YAML indentation matters, so an incorrectly indented entry may not be recognised.

iOS CocoaPods Error

First check that CocoaPods is available:

pod --version

Then update the project’s iOS dependencies if required:

cd ios
pod install
cd ..

If the error mentions incompatible deployment targets, pod versions, or a specific plugin, address that message directly. Reinstalling CocoaPods repeatedly will not resolve a plugin compatibility problem.

App Builds but Does Not Launch

Read the final lines of the terminal or Debug Console. A successful compilation does not always mean successful installation or startup.

Common causes include insufficient device storage, an offline emulator, an Android package installation conflict, iOS signing errors, or a runtime exception during application initialisation.

Run flutter run -v when the normal output does not provide enough information:

flutter run -v

The verbose log is extensive, but the first meaningful error usually indicates whether the failure occurred during dependency resolution, compilation, installation, signing, or application startup.

A Practical Setup Verification Sequence

When a Flutter app refuses to run, checking components in a fixed order saves time. Start by confirming that the terminal recognises Flutter. Next, run Flutter Doctor and resolve errors for the selected platform. Then confirm that the project root is open, dependencies have been fetched, and the target appears under flutter devices.

Only after those checks should you investigate the application code.

This order matters because it separates environment failures from project failures. If the default Flutter starter app cannot run, the problem is almost certainly in the development setup. If a new starter project runs but an existing project does not, the issue is more likely related to that project’s dependencies, platform configuration, or code.

Conclusion

Running a Flutter application in VS Code is straightforward once the SDK, editor extension, platform tools, and target device are correctly connected.

Install Flutter and verify its PATH first. Then validate the setup with flutter doctor -v, open the project directory containing pubspec.yaml, select a detected device, and press F5 or run flutter run.

When something fails, avoid changing several settings at once. Check the environment in a consistent order: Flutter command, Doctor output, project detection, package resolution, device connection, and finally the application code. This makes the actual cause much easier to identify and prevents a small setup issue from becoming a lengthy debugging session.