Open in app

Sign in

Write

Sign in

Setting up FVM (Flutter Version Management) properly

Sanjib Maharjan
12 min readMay 11, 2021

--

Managing different versions is one of the important topics in software development. Normally there can only be one version of flutter at a time and switching between the version takes a little bit longer since it downloads the SDK and libraries from the beginning. Hence If we are working on more than one project with different versions then it becomes a little bit hectic to switch versions between the project. In a real scenario, a person might have a lot of projects and it is not assured that they could run into the same flutter version because some projects might need a specific version of Flutter.

In Flutter we can manage different versions of Flutter using FVM aka Flutter Version Management, a simple CLI to manage different Flutter versions on a per-project basis.

Fvm Commands

  • “fvm releases”: List the available flutter versions
  • “fvm install <version>”: to install flutter version 2.0.6 the command should be “fvm install 2.0.6”.
  • “fvm list”: to list all the flutter versions installed in our system using fvm
  • “fvm remove <version>”: to remove specified flutter version
  • “fvm global <version>”: to set the global flutter version
  • “fvm use <version>”: to set the flutter version ProjectWise. And to do that we must run this command within the root of the flutter projects or else it won't work. Also if the version is not available in the system then it will first install it and then make use of it.
  • “fvm doctor”: to display the current fvm version and its configuration

Why FVM?

What’s so great about a version manager that allows us to switch the flutter versions? Why should we even care about it? Cant we just code without it? Well, it all depends on us. If we have to work on only a single project with only one flutter version or on multiple projects but all of them run on only one flutter version then we’re better off without a version management tool like FVM. But if we have to deal with multiple flutter versions then FVM is one of the best options for us because switching flutter versions is quite tricky and time-consuming in Flutter.

Different ways to switch flutter versions

  1. Flutter has two commands flutter upgrade and flutter downgrade to upgrade to the latest stable release and downgrade to the last current version. For example: If our current flutter version is 2.0.0 and the stable release is 3.0.0 then flutter upgrade will upgrade our current version to 3.0.0 and flutter downgrade will revert our current version back to 2.0.0. i.e These commands are useful to switch between these two versions only and the switching is time-consuming since switching requires the re-downloading of the SDK every time. Also, these commands wouldn't work if we were to switch other versions besides 2.0.0 and 3.0.0.
  2. Channels: We can also check out the flutter channels for the versions that we need. Run flutter channel to list the available channels. And to switch to any of the listed channels, we can run flutter channel <channel_name> followed by flutter doctor downloading the required SDKs. Finally, run flutter --version to check the version in that particular channel.
  3. Switching to a specific flutter version: We can only switch to those versions that are available in the flutter channels with both of the above-listed methods. With this method, we can switch to any version that is available, and for that first visit the flutter repository to check if the version is available.
    Flutter repository:https://github.com/flutter/flutter
    On the website, find the branch dropdown and click it to make the dropdown popup appear with two tabs branches and tags. Click the Tags tab and search for the version that you are trying to switch. If you cannot find the version there then the version probably doesn't exist. And if the tag name with your version is there then you can use that version.
    Now we can switch to that version by going to the flutter directory in the terminal and switching to that tag_name.
    Locate the directory where flutter SDK is stored: where flutter or if the above command doesn`t work then run flutter doctor -v which outputs the directory where flutter is installed in the first line of each section.
    Switch the flutter version: Open the terminal and navigate to the flutter directory by running the command cd path_to_flutter_directory. Now on the flutter directory run the git command git checkout tag_name. For example, if the version is 3.0.0 then the command would be:
    git checkout 3.0.0
    Finally, run flutter doctor to download the necessary files and folders and make sure everything is working fine.
    Run the command flutter —-version and it should output your version.

All of the above-mentioned methods are very time-consuming and complex. It redownloads the SDK files again even though we had already used that version previously. But with FVM the version switching process is very simple and short. We just have to install it and learn some of its commands which are very easy as compared to the above-mentioned steps. Also, it maintains each version that we switched in the system's local cache so that it does not have to redownload all the required files when we switch back to it.

Installation (macOS, Ubuntu, and other UNIX systems)

  • Standalone Installation— (recommended)
    Make sure you have brew package manager installed and if not visit the website https://brew.sh/ to install it.
    Now to install/uninstall fvm run the following commands in the terminal.
#run the following two commands to install fvmbrew tap leoafarias/fvm
brew install fvm#run the following two commands to uninstall fvmbrew uninstall fvm 
brew untap leoafarias/fvm#Also delete the fvm cache directory if you want to remove all the cached files and folders. The cache directory could be known by using the command fvm list
  • Pub package Installation
    Make sure you have dart installed and if not visit the website https://dart.dev/get-dart to install it.
    Now to install/uninstall fvm run the following commands in the terminal.
#run the following command to install fvmdart pub global activate fvm#run the following command to uninstall fvmdart pub global deactivate fvm#Also delete the fvm cache directory if you want to remove all the cached files and folders. The cache directory could be known by using the command fvm list

Installation (Windows)

  • Standalone Installation — (recommended)
    Make sure you have chocho package manager(chocolatey) installed and if not visit the website https://docs.chocolatey.org/en-us/choco/setup to install it.
    Now to install/uninstall fvm run the following commands in the terminal.
#run the following command to install fvmchoco install fvm#run the following command to uninstall fvmchoco uninstall fvm#Also delete the fvm cache directory if you want to remove all the cached files and folders. The cache directory could be known by using the command fvm list
  • Pub package Installation
    Make sure you have dart installed and if not visit the website https://dart.dev/get-dart to install it.
    Now to install/uninstall fvm run the following commands in the terminal.
#run the following command to install fvmdart pub global activate fvm#run the following command to uninstall fvmdart pub global deactivate fvm#Also delete the fvm cache directory if you want to remove all the cached files and folders. The cache directory could be known by using the command fvm list

Global and Project specific versions

We can have the global version set which can be done by running the command: fvm global <version>
Now this version will be used for every project unless we set the version project-wise. We can set the version project-wise by running the command fvm use <version> in the root of the project directory.

We might run into the following warning while setting the global flutter version.

This error is because we already have flutter installed without using fvm and the flutter path points to /Users/crystal/codehome/tools/flutter/bin which is where we had installed flutter before. To fix this and use the global version set by fvm, we have to set the flutter path to /Users/crystal/codehome/tools/flutter/bin.

Replace the path with the one instructed in the warning in the environment variables. If you are running in macOS or UNIX systems then the path might be in the files like .zshrc, .bashrc, .bash_profile etc. In the following example, the path is in the .zshrc file located in the user's root directory.

Save the file and restart the terminal or run the command source ~/.zshrc to address the changes we made in the environment variables.
If you are running a windows system, the approach is a little bit different. Open start search by clicking the window button then type env and select Edit Environment Variables. From the popup click Environment Variables on the bottom right side. From the new popup, you can find and replace the flutter path and restart the terminal.

Configuring project-wise flutter version

We can configure a separate flutter version for each project that we are working on. To check if it is set up for the project, go to the project directory and run the command fvm list

Here no version has been set up for the project yet. To use version 2.0.2, just run the command fvm use 2.0.2 .
Here the version marked with (global) text is the current global version and if no global version is set project-wise then this global version will be used.

Now run the command fvm listagain.

Now we can see (active) text beside the version “2.0.2” which indicates that it has been selected for the given project. To switch to a different version we have to just run the command fvm use <version>

Also, notice the Cache Directory path in the above screenshot which is set to /Users/crystal/fvm/versions where all the versions will be persisted temporarily as long as we have enough space in the system's memory. Please have a look at the next screenshot for its visual content. This location can also be changed using the command fvm config —-cache-path <NEW_CACHE_PATH> or setting the FVM_HOME environment variable.

Note: If the version is set project-wise properly then a folder named .fvm must be present at the root of that particular project. This folder contains the information about the flutter version that is set project-wise. It also contains the folder .fvm/flutter_sdk which is the symbolic link to the flutter version set project-wise by fvm.
For example, let's say we have the fvm cache directory set to /Users/crystal/fvm/versions where crystal is the username of my computer. Now all the flutter versions will be installed in this cache location.

We have a flutter project in the location /Users/crystal/projects/project2 and we have version 2.8.1 set for this project. So, this project must have .fvm folder in it with the absolute path /Users/crystal/projects/project2/.fvm and /Users/crystal/projects/project2/.fvm/flutter_sdk is the symbolic link to /Users/crystal/fvm/versions/2.8.1 ie it points to the location /Users/crystal/fvm/versions/2.8.1. If we switch the version to 2.8.0 by running the command fvm use 2.8.0 then /Users/crystal/projects/project2/.fvm/flutter_sdk will simply point to the directory of version 2.8.0 ie/Users/crystal/fvm/versions/2.8.0.

Note: To unset the version project-wise we just have to delete the .fvm folder in which case it will start using the global version.

Note: After switching the flutter version it is suggested to restart the IDE(if you are using any) to make sure it has been properly configured with the switched version.

IDE Configuration

We should properly configure IDE and fvm for better support for different development environments. FVM creates a relative symlink in the projects it is set up from ”.fvm/flutter_sdk“ to the cache of the selected version.

Android studio

  1. In the android studio, Go to Languages & Frameworks -> Flutter or search for Flutter and change the Flutter SDK path.
  1. Copy the absolute path of the fvm symbolic link in your root project directory. Example: /absolute-path-to-the-project/.fvm/flutter_sdk
    You can also set the path to the global version here if no version is set project-wise in certain flutter projects.
    Note: The .fvm folder is a hidden file.
    Show the hidden content:
    MacOs: Cmd + Shift + Period(.)
    Ubuntu: Ctrl + H
  2. Apply the changes.
  3. Restart Android Studio to see the new settings applied.

With this configuration, Android studio will use the version that is set by fvm project-wise. Also, it should be noted that this should be configured only once for each project. Even though we switch between different projects, the configuration for each project that is set before remains intact.

Here “/Users/crystal/codehome/tuts/fvm/fvm_test_project/” is the project directory.

VS Code(Visual Studio Code)

Method 1: — Automatic Switching(Recommended)

Open the “.vscode/settings.json” file of the project directory and make the following changes. This file may not be present and if not just create it.

{
  "dart.flutterSdkPath": ".fvm/flutter_sdk",
  // Remove .fvm files from search
  "search.exclude": {
    "**/.fvm": true
  },
  // Remove from file watching
  "files.watcherExclude": {
    "**/.fvm": true
  }
}

This configuration is similar to the one that we did for Android Studio. ie. VS Code will use the version that is set by fvm project-wise.

Method 2: — View all SDKs (Manual switching)

VSCode has the ability for you to switch between all installed Flutter SDKs using Flutter: Change SDK command in the command palette.
Open Command Palette:
macOS: Cmd + Shift + P , Others: Ctrl + Shift + P
But before running the command update following in the “.vscode/settings.json” file

{
  "dart.flutterSdkPaths": ["/Users/usr/fvm/versions"]
}

This lists all versions of flutter installed using fvm. Alternately we can also add one or more versions manually to list only those versions by VSCode.

{
  "dart.flutterSdkPaths": [
    "/Users/crystal/fvm/versions/stable",
    "/Users/crystal/fvm/versions/2.0.6"
  ]
}

Now to change the current Flutter version open the command palette and run Flutter: Change SDK. You should see only those versions as shown in the above code snippet. In this case, only “stable” and “2.0.6” will be listed to be selected and once we select the version following entry will be automatically updated by the command in the “.vscode/settings.json” file given that we chose version 2.0.6.

{
  "dart.flutterSdkPaths": [
    "/Users/crystal/fvm/versions/stable",
    "/Users/crystal/fvm/versions/2.0.6"
  ],//following entry is automatically added after running the command    //Flutter: Change SDK in the command palette and choosing version //2.0.6  "dart.flutterSdkPath" : "/Users/crystal/fvm/versions/2.0.6"
}

Access to flutter revisions and custom versions

To install a specific revision of flutter: run the command
fvm use f4c74a6ec3 , f4c74a6ec3 is the short commit hash.

We can also use the custom flutter version which is forked from the fvm repository. To make the use of custom version, run the command fvm use {custom_name} . And this custom version must be within the fvm cache directory and custom_name is the directory at the root of the fvm cache directory.

If you have reached here then pat yourself on back because you have completed the fvm set up properly and you can switch the flutter version between projects easily in less time.

Note: For the projects where the flutter version is set project wise, don't forget to add “fvm” as a prefix in every flutter-related command.

For example :

“ flutter pub get” becomes “ fvm flutter pub get”,

“ flutter packages pub run build_runner build” becomes “ fvm flutter packages pub run build_runner build”,

“ flutter build apk” becomes “ fvm flutter build apk” and so on.

And If you do not prefix the flutter commands with fvm then the global version will be used.

This is the end of the article and please do leave the suggestions or questions if any in the comment section below. Also, feel free to clap 👏 as much as you can and share with other people to show support. Thank you!

#flutter, #fvm, #flutter_version_management, #version_management, #install_fvm_macOs, #install_fvm_windows, #fvm_video_tutorial, #multiple_flutter_version_without_fvm

--

--

Sanjib Maharjan

Written by Sanjib Maharjan

70 Followers

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams