Managing Flutter SDK Versions per Project with FVM (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 point the global flutter command at an FVM-managed version.

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 and putting it on your PATH, so the plain flutter command uses it.
Running fvm flutter inside a project to use that project's pinned version.

Installation

Windows

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

Bash

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:

Bash

dart pub global activate fvm

Alternatively, you can use Homebrew:

Bash

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:

Bash

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

Basic Usage

Install a Flutter Version

Bash

fvm install 3.24.0

To install the latest version from the stable channel:

Bash

fvm install stable

List Installed Versions

Bash

fvm list

List Available Releases

Bash

fvm releases

Pin a Version to a Project

Navigate to the project root and run:

Bash

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 (.fvm/flutter_sdk) inside the .fvm/ directory.

Run Flutter Commands via FVM

Bash

fvm flutter run
fvm flutter build apk
fvm flutter pub get

fvm flutter looks for the SDK in this order: the project's .fvmrc → an ancestor directory's .fvmrc → the global version (fvm global) → the system PATH. To use a project's pinned version, run commands through it. An alias like alias f="fvm flutter" saves typing.

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 SDK. To make flutter point to FVM's global version, follow these steps.

Step 1: Set the FVM Global Version

Bash

fvm global 3.24.0

This designates a default Flutter version managed by FVM.

Step 2: Update Your PATH

Windows

Open Edit the system environment variables (Win + S → search "environment variables").
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.
Remove that path.
Add the following path instead:

TEXT

%LOCALAPPDATA%\fvm\default\bin

Open a new terminal and verify:

Bash

flutter --version
where flutter

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

macOS

Open .zshrc or .bashrc:

Bash

vi ~/.zshrc

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

Bash

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

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

Apply changes and verify:

Bash

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 — including inside projects. To use a project's .fvmrc version, run fvm flutter.

Bash

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

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

If you want plain flutter to use the project version, you need a small wrapper script that calls fvm flutter; see Running Flutter in the FVM docs.

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

IDE Configuration

VS Code

By default FVM updates VS Code settings when you run fvm use. To configure it yourself, create or edit .vscode/settings.json at the project root:

JSON

{
  "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. FVM doesn't change Android Studio settings automatically.

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. It holds local files such as symlinks and shouldn't be tracked. The FVM docs recommend ignoring the whole .fvm/ directory, and by default FVM updates .gitignore for you:

TEXT

.fvm/

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

Command Cheat Sheet

Command	Description
`fvm install <version>`	Install a specific Flutter version
`fvm use <version>`	Pin a version to the current project
`fvm global <version>`	Set the global default version
`fvm list`	List installed versions
`fvm releases`	List available releases
`fvm remove <version>`	Remove a specific version
`fvm flutter <command>`	Run a Flutter command via FVM
`fvm doctor`	Diagnose the FVM environment

Summary

Pin a version per project with fvm use <version>, and run fvm flutter to use it.
With fvm global and a PATH update, the plain flutter command points at FVM's global version.
You can switch over gradually without removing your existing Flutter SDK first.