Flutter Version Management with FVM: Your New Favorite Tool

Introduction

Have you ever faced a situation when you just upgraded your version of Flutter, but the project you were working on is not yet ready to migrate to the new version? Now you have to think about how to downgrade your Flutter SDK. Or a situation when you are working on multiple projects at the same time, and each one uses a different Flutter version? And you have to constantly switch between them, which can be very long and tiring.

If you’ve encountered these or other problems with Flutter versions, then you might be thinking, “Hmm, there must be an easier way to deal with this.” And there is. Here is where FVM comes into play.

💡
Flutter Version Manager (FVM) – a simple CLI to manage Flutter SDK versions. It allows you to have multiple versions of Flutter and easily switch between them.

Installation

You have a few options to install FVM:

  • Install it as pub package:
    dart pub global activate fvm
    
  • Install it by running the following command from Homebrew package manager (for MacOS and Linux):
    brew tap leoafarias/fvm
    brew install fvm
    
  • Install it by running the following command from your command line or PowerShell (for Windows):
    choco install fvm
    

Configuration

You can set you cache path (location where the Flutter SDK versions will be stored) running the following command:

fvm config --cache-path <CACHE_PATH>

To list your configurations:

fvm config

You can also configure your IDE for better FVM experience. More info you can find in the documentation.

Basic Commands

Here is a list of basic FVM commands:

  • To set Flutter SDK version to your project you can use the following command:

    fvm use {version}
    

    If you don’t have specified version in your cache directory, FVM will ask if you want to install it.

  • To list all installed Flutter SDK versions:

    fvm list
    
  • To install the desired Flutter SDK version:

    fvm install {version}
    

    If you don’t specify version here, the version found in project config will be installed.

    Sometimes Flutter release can be displayed on multiple channels. FVM will sort them by stability and use the most stable one. FVM uses the following priority: Stable → Beta → Dev.

    You can force FVM to install Flutter SDK version from a specific channel:

    fvm use {version@channel}
    

    for example:

    fvm use 2.2.2@beta
    
  • To list all Flutter SDK releases available to install:

    fvm releases
    
  • To remove Flutter SDK version:

    fvm remove {version}
    

    Will impact any project that depend on that version!

  • To show information about environment and project configuration:

    fvm doctor
    
  • To spawn a command on any installed Flutter SDK:

    fvm spawn
    

    for example:

    fvm spawn master analyze
    

    Will run Flutter analyze on the master channel.

.fvm folder

After running fvm use command .fvm directory will be created in your project.

  • .fvm/flutter_sdk - a relative symlink in your project to the cache of the selected version. It is recommended to add it to your .gitignore file. Just copy and paste the following line:

    .fvm/flutter_sdk
    
  • .fvm/fvm_config.json defines what version of Flutter and flavors (more on that later) you are using in this project.

Running Flutter App

Normally if you want to run your project you will use flutter run command. If you want to use FVM you should run fvm flutter run instead. You can do the same with other commands – just add fvm prefix:

fvm flutter {command}
# instead of
flutter {command}

Same with dart commands:

fvm dart {command}
# instead of 
dart {command}

You can call desired installed SDK directly using the symlink:

.fvm/flutter_sdk/bin/flutter {command}

Project Flavors

You can also set Flutter SDK versions for your project flavors.

💡
Flavors are build configurations that allow you to create separate environments for your application using the same code base.

To specify a Flutter SDK version for a flavor you can use the following command:

fvm use {version} --flavor {flavor_name}

To list all of your flavors:

fvm flavor

To choose which flavor to use:

fvm flavor {flavor_name}

Examples:

fvm use 3.10.4 --flavor dev
fvm use 3.7.0 --flavor prod
fvm flavor dev

It will create the following configuration in fvm_config.json file for your project:

{
    "flutterSdkVersion": "3.10.4",
    "flavors": {
        "dev": "3.10.4",
        "prod": "3.7.0"
    }
}

When we run the project Flutter SDK version 3.10.4 will be used.

Advanced

  • You can use your custom Flutter versions (forks). For this, the folder with this version should be inside FVM cache directory. You can set your version by running fvm use command:

    fvm use {custom_name}
    
  • You are able to install and bind a specific framework revision by providing the git commit or short hash:

    fvm use f4c74a6ec3
    

Conclusion

Flutter Version Manager (FVM) allows developers to easily install, configure, and switch between Flutter versions, making the development process more efficient and streamlined. With features like project flavors and support for custom Flutter versions, FVM offers flexibility and convenience. By utilizing FVM, developers can focus on building their applications without being burdened by version management complexities.