How to switch Flutter versions per project with FVM

How to install FVM on Mac and Windows

• Mac or Linux: the install script, curl -fsSL https://fvm.app/install.sh | bash
• Mac with Homebrew: brew tap btwld/fvm, then brew install btwld/fvm/fvm. The old leoafarias/fvm tap has moved, so untap it if you used it before.
• Windows: choco install fvm with Chocolatey, or download the windows-x64 or windows-arm64 zip from FVM's GitHub releases, extract it and add the fvm folder to Path.
• Any system with Dart: dart pub global activate fvm

Open a new terminal and run fvm --version to check it worked. FVM keeps every Flutter version in one cache, ~/fvm/versions by default, or wherever FVM_CACHE_PATH points.

How to pin a Flutter version to a project

Run fvm use in the project's root folder. It downloads the version if it isn't cached, writes it to .fvmrc, creates the .fvm folder with a flutter_sdk link to the cached SDK, adds .fvm to .gitignore, updates the VS Code settings and runs flutter pub get. Commit .fvmrc, not .fvm. A teammate who clones the project runs fvm install with no version and gets the pinned one.

From then on, prefix Flutter commands with fvm so they use the project's version. FVM blocks flutter upgrade on a pinned release: to move up, run fvm use with the newer version.

cd my_app
fvm use 3.35.5          # or: fvm use stable --pin
fvm flutter --version
fvm flutter run

How to make VS Code and Android Studio use the FVM version

• VS Code: fvm use sets dart.flutterSdkPath in the project's .vscode/settings.json to the pinned version under .fvm/versions. Reload the window if the Dart extension hasn't picked it up. If .fvmrc has "updateVscodeSettings": false, FVM leaves the file alone and you set the path yourself.
• Android Studio: open Settings (Android Studio > Settings on a Mac, File > Settings on Windows), then Languages & Frameworks > Flutter, and set Flutter SDK path to the full path of the project's .fvm/flutter_sdk folder, not its bin folder. Click Apply.
• Some Android Studio versions save the real cache path instead of the link, so the IDE stays on the old version after you switch. Check the version shown in that settings page after each fvm use, and select the .fvm/flutter_sdk path again if it's stale. fvm doctor shows the saved path.
• Windows: the flutter_sdk link is a symlink, which needs Developer Mode or administrator rights. Without them FVM skips the link, so point the IDE at the version's folder in the FVM cache instead.

Set a global version, and use the pin in CI

fvm global sets the Flutter used outside pinned projects. FVM links it at ~/fvm/default (C:\Users\you\fvm\default on Windows). Put its bin folder on your PATH before any other Flutter install, then check with which flutter on a Mac or where flutter on Windows. fvm global --unlink removes the global setting.

In CI, FVM's docs use three steps: install FVM (dart pub global activate fvm, or the install script on Mac and Linux runners), run fvm install with no version so it reads .fvmrc, then build with fvm flutter, for example fvm flutter build apk --release. CI then follows the project's pin with no second place to update.

fvm global 3.35.5

# Mac: add to ~/.zprofile
export PATH="$HOME/fvm/default/bin:$PATH"

How to remove old Flutter versions

Each cached version is a full Flutter SDK with its own git history. fvm list shows every cached version, which one is global or selected in the current project, and how many projects FVM has recorded as pinning it. Versions nothing pins are marked Unused, but FVM only records projects it has seen, so treat that as a hint. fvm remove deletes one version, fvm remove --all deletes every cached one, and fvm destroy deletes the whole cache.

fvm list
fvm remove 3.22.3

See which projects use each version with Stackyard

Stackyard reads FVM's cache and scans your project folders for .fvmrc files, so every installed Flutter version shows the projects that pin it, and the ones nothing uses stand out. Removing a version moves it to the Trash or Recycle Bin after showing you exactly what will happen. If a project pins a version you don't have, it offers to install it with FVM. It's free and open source, for Windows 10 or 11 and macOS 12 or later.

Questions

How do I change the Flutter version in VS Code?

Run fvm use with the version in the project folder. FVM writes dart.flutterSdkPath into .vscode/settings.json, and the Dart extension switches to it, sometimes after a window reload.

How do I change the Flutter SDK version in Android Studio?

Open Settings, then Languages & Frameworks > Flutter, and set Flutter SDK path to the project's .fvm/flutter_sdk folder. Check the version shown there after each switch, because some Android Studio versions keep the old cache path.

What is the difference between fvm use and fvm global?

fvm use pins a version to one project through its .fvmrc file. fvm global sets the version for every terminal and project that has no pin, through ~/fvm/default.

Should I commit the .fvm folder?

No. Commit .fvmrc, which holds the version, and ignore .fvm, which only holds links to your machine's cache. FVM adds .fvm to .gitignore for you by default.

How do I install FVM on Windows?

Use choco install fvm with Chocolatey, or download the Windows zip from FVM's GitHub releases and add the extracted fvm folder to Path. dart pub global activate fvm also works if Dart is installed.