Managing multiple flutter version with fvm

It's been awhile since i work with flutter. A lot of my project are still using older version of flutter prior version 2. Migrating these project can be cumbersome and need a lot of consideration before even began migrate those project. So for quite some times, i've been change path to my flutter installation manually (yup, really) until now i have 4 version of flutter to switch between project and this has become a pain in the arse.

So now is the best time to start using fvm whcih short for flutter version manager. It's kind of like using rvm for ruby but for flutter. If you are still new with flutter, you can stay where you are until you hit the bump like or you can just start using fvm right now to avoid that.

To make it short what we are doing is replacing the manual steps:

Old step:

  1. Download flutter vX.X.X
  2. Unzip
  3. Change path
  4. Open project
  5. Repeat from step 1 or 3 for project that use different flutter version

New step:

  1. Install fvm
  2. update sdk path to fvm path
  3. run fvm install 2.8.1 and other version
  4. use flutter version based on project fvm use 2.8.1 or other version base on project b. run fvm global 2.8.1 or other version base on project (to start new project and etc)
  5. Now we just have 2 step at max when change project and no need to bother with the sdk path again.

Advantage of using fvm

  • run flutter project based on version set in .fvm/fvm_config.json
  • easily to switch global flutter
  • easily use beta or stable flutter channel
  • use different version for each project and app flavor

Step 1 - installing fvm

Without further ado, let's get started. First we want to install fvm. Open up your console or powershell.

# mac or linux
brew tap leoafarias/fvm
brew install fvm

# windows - there are no fvm install available on winget yet
# follow chocolatey installation from
choco install fvm

Step 2 - Update your path to flutter sdk

So in here we need to update the flutter sdk path from flutter_vX.X.X/bin to fvm/default/bin in your .bash_profile or .zprofile. For windows add C:/Users/<YOUR_USERNAME>/fvm/default/bin your environment variables path.

export PATH="$PATH:/Users/<YOUR_USERNAME>/fvm/default/bin"

# windows add to path environment variable

Step 3 - Install required flutter version

# fvm install <flutter-version>
fvm install 1.22.6
fvm install 2.8.1
fvm install 3.0.3
fvm install x.x.x

Step 4 - Set project flutter version

So let say my new project using latest flutter 2.8.1. So in the project directory, i will run fvm use 2.8.1

fvm list
fvm use 2.8.1

Wait there's a flutter_sdk folder in my project ? Does each project now have it's own flutter installion ? Nope, fvm simply symlinked the cached version in fvm cache folder. So we need to add this to our .gitignore file. But we still want .fvm/fvm_config.json to be include in git.

# .gitignore

Step 5 - Install the dependencies and run the app

Now in the project path

fvm flutter pub get
fvm flutter run

Switching global flutter version

fvm list # show list of version that you have
fvm global 2.8.1 # or any version

Use existing flutter sdk with fvm

Okay this is just my kind of twist because i was lazy to redownload multiple flutter sdk and i already have them. To not waste time downloading sdk version that we already have we simply have to rename the sdk folder to its version number. eg i have flutter_v1.22.8, so rename it to 1.22.8. And just move this folder to fvm sdk cache folder. The default cache folder is at /User/USERNAME/fvm/versions.

so now it kinda look like this

├── default
└── versions/
    ├── 1.22.8
    └── 2.8.1

So now we can check the version now exist in fvm list

> fvm list
Cache Directory:  /Users/noxasch/fvm/versions

2.8.1 (global)


So to conclude let we see the common fvm and flutter command that we will likely use

# common fvm command
fvm list
fvm install X.X.X
fvm doctor # show environmetn and project config

# per project command
fvm use X.X.X
fvm flutter pub get
fvm flutter run

# global fvm
fvm global x.x.x
flutter --version
flutter run
flutter pub get

Bonuse fvm gui with flutter sidekick

After we have fvm and flutter installed we can now install sidekick for more visual approach ot manage our flutter version

For mac and linux (also windows 7 and 10), download from their github release directly. For windows 10 and 11 download from microsoft store

That's it everyone. If you want to know more like change flutter channel or specific sdk revision, feel free to visit the docs.

What not to do when using fvm

  • Do not use flutter upgrade, use fvm install X.X.X