Managing Flutter SDK Versions per Project — The Complete FVM Guide (Windows / macOS)

When you're juggling multiple Flutter projects, it's common to run into situations where each project requires a different SDK version. Manually swapping SDKs every time is tedious and error-prone. FVM (Flutter Version Management) lets you cleanly isolate Flutter SDK versions per project and even replace the global flutter command so that version switching happens automatically.

This guide covers installing FVM on both Windows and macOS, and migrating your existing Flutter SDK setup to FVM.

What is FVM?

FVM is a CLI tool for managing Flutter SDK versions on a per-project basis. Its core features include:

• Assigning a specific Flutter SDK version to each project.
• Setting a global default version so the flutter command works as usual.
• Automatically resolving the correct version when you enter a project directory.

Installation

Windows

If you already have Dart installed (bundled with the Flutter SDK), you can install FVM directly:

dart pub global activate fvm

If the fvm command is not recognized after installation, make sure %LOCALAPPDATA%\Pub\Cache\bin is included in your system PATH. This is usually added automatically when you install the Flutter SDK, but you may need to add it manually.

macOS

The Dart-based installation is the same:

dart pub global activate fvm

Alternatively, you can use Homebrew:

brew tap leoafarias/fvm
brew install fvm

If fvm is not recognized on macOS, verify that $HOME/.pub-cache/bin is in your PATH. Add the following to your .zshrc or .bashrc:

export PATH="$HOME/.pub-cache/bin:$PATH"

Basic Usage

Install a Flutter Version

fvm install 3.24.0

To install the latest version from the stable channel:

fvm install stable

List Installed Versions

fvm list

List Available Releases

fvm releases

Pin a Version to a Project

Navigate to the project root and run:

cd my_project
fvm use 3.24.0

This creates a .fvmrc file at the project root and sets up a symlink to the SDK inside the .fvm/ directory.

Run Flutter Commands via FVM

fvm flutter run
fvm flutter build apk
fvm flutter pub get

Replacing Your Existing Flutter SDK with FVM

Installing FVM doesn't require you to remove your existing Flutter SDK right away. FVM manages its own SDK copies in a separate directory, so there's no conflict. However, if you run flutter in the terminal, it will still resolve to your original global SDK. To make flutter point to the FVM-managed version, follow these steps.

Step 1: Set the FVM Global Version

fvm global 3.24.0

This designates a default Flutter version managed by FVM.

Step 2: Update Your PATH

Windows

1. Open Edit the system environment variables (Win + S → search "environment variables").
2. In the Path variable (user or system), find the existing Flutter SDK path. It's usually something like C:\flutter\bin or C:\src\flutter\bin.
3. Remove that path.
4. Add the following path instead:

%LOCALAPPDATA%\fvm\default\bin

1. Open a new terminal and verify:

flutter --version
where flutter

If where flutter points to %LOCALAPPDATA%\fvm\default\bin\flutter, you're all set.

macOS

1. Open .zshrc or .bashrc:

vi ~/.zshrc

1. Remove the old Flutter SDK path and replace it with the FVM path:

# Old (remove)
# export PATH="$HOME/flutter/bin:$PATH"

# FVM-based (add)
export PATH="$HOME/fvm/default/bin:$PATH"

1. Apply changes and verify:

source ~/.zshrc
flutter --version
which flutter

If which flutter points to the FVM default path, you're good to go.

Step 3: Verify

Now the flutter command uses the FVM global version anywhere on your system. Inside a project directory with a .fvmrc file, the project-specific version is automatically applied.

# Outside a project → uses global version
flutter --version

# Inside a project → uses version from .fvmrc
cd my_project
flutter --version

You can safely delete the old Flutter SDK folder once you've confirmed everything works.

IDE Configuration

VS Code

Create or edit .vscode/settings.json at the project root:

{
  "dart.flutterSdkPath": ".fvm/flutter_sdk"
}

This tells the Dart/Flutter extension to use the FVM-managed SDK for the project.

Android Studio / IntelliJ

Go to Settings → Languages & Frameworks → Flutter, and set the Flutter SDK path to the absolute path of .fvm/flutter_sdk inside your project.

Examples:

• Windows: C:\Users\username\projects\my_project\.fvm\flutter_sdk
• macOS: /Users/username/projects/my_project/.fvm/flutter_sdk

.gitignore Setup

FVM creates a .fvm/ directory in your project. The flutter_sdk inside it is a symlink and should not be tracked by version control. Add the following to .gitignore:

.fvm/flutter_sdk

The .fvmrc file should be committed so that team members use the same Flutter version.

Command Cheat Sheet

Wrap Up

FVM gives you independent Flutter SDK management per project. Combined with fvm global and a PATH update, you can keep using the familiar flutter command while getting automatic per-project version switching. It's especially valuable when maintaining multiple projects simultaneously or aligning SDK versions across a team. Since it works alongside your existing Flutter SDK with zero conflicts, there's no reason not to give it a try.