fenv is a CLI tool that helps manage multiple versions of flutter SDKs in your local machine. fenv does never require any other dependencies even Dart(‼️) because it consists of a single static-linking executable.

This is a hobby project, which is highly inspired by pyenv. Any kinds of feedbacks are welcome.

• fenv
  • Table of contents
  • fenv vs. FVM
  • Supported OS and CPU architecture
  • How to install fenv
    • Install the latest version
    • Install an older version
  • How to use
    • List up all the available Flutter SDKs
    • List up all the installed Flutter SDKs
    • Install the specific version of Flutter SDK
    • Install the latest snapshot of a channel Flutter SDK
    • How to specify the globally used Flutter SDK
    • How to specify the locally used Flutter SDK
    • See more help
  • How to migrate
    • From v0.0.x to v0.1.x
  • Trouble shootings
    • If "fenv init" and "fenv init -" misunderstand your shell
    • If the .flutter-version file exists but not the corresponding flutter SDK isn't installed
    • If IDE could not find Flutter SDK path and Dart path correctly
    • If Dart-based CLI tools (such as "melos") do not work well after switching Flutter SDK

fenv is the tool to solve the completely same problem that FVM attempts to solve. However, fenv is born to address the weakness of FVM.

As you can see from the above table, fenv does neither require the annoying fvm prefix to run a flutter command nor require manual setup of SDK paths for IDEs. fenv is an out-of-the-box tool that is developed for professional Flutter developers.

• Linux x86_64
• Linux aarch64
• MacOS x86_64
• MacOS aarch64

1. Execute the following command in your terminal:

   $ curl -fsSL "https://fenv-install.jerry.company" | bash

2. When the installation ends up, you will see instruction like:

   # Installation succeeds
   # Please execute the following command
   
   $HOME/.fenv/bin/fenv init
   
   # And follow the instructions if you have not setup `fenv` yet:

3. Execute $HOME/.fenv/bin/fenv init then follow the next instructions. fenv will suggest the different instructions guessing your shell.

   • zsh:

     # Load fenv automatically by appending the following to
     # ~/.zprofile (for login shells)
     # and ~/.zshrc (for interactive shells) :
     
     export FENV_ROOT="$HOME/.fenv"
     command -v fenv >/dev/null || export PATH="$FENV_ROOT/bin:$PATH"
     eval "$(fenv init -)"
     
     # Restart your shell for the changes to take effect:
     
     exec $SHELL -l

   • bash:

     # Load fenv automatically by appending the following to
     # ~/.bash_profile if it exists, otherwise ~/.profile (for login shells)
     # and ~/.bashrc (for interactive shells) :
     
     export FENV_ROOT="$HOME/.fenv"
     command -v fenv >/dev/null || export PATH="$FENV_ROOT/bin:$PATH"
     eval "$(fenv init -)"
     
     # Restart your shell for the changes to take effect:
     
     exec $SHELL -l

   • fish:

     # Add fenv executable to PATH by running
     # the following interactively:
     
     set -Ux FENV_ROOT $HOME/.fenv
     fish_add_path $FENV_ROOT/bin
     
     # Load fenv automatically by appending
     # the following to ~/.config/fish/conf.d/fenv.fish:
     
     fenv init - | source
     
     # Restart your shell for the changes to take effect:
     
     exec $SHELL -l

   • ksh:

     # Load fenv automatically by appending the following to
     # ~/.profile :
     
     export FENV_ROOT="$HOME/.fenv"
     command -v fenv >/dev/null || export PATH="$FENV_ROOT/bin:$PATH"
     eval "$(fenv init -)"
     
     # Restart your shell for the changes to take effect:
     
     exec $SHELL -l

4. Remove FLUTTER_HOME, FLUTTER_SDK environmental variables if exist.

5. Eliminate any existing <FLUTTER_SDK>/bin from your PATH.

• You can specify the target version of fenv with the FENV_VERSION environment variable.

• Specify the version tag explicitly like:

  $ curl -fsSL "https://fenv-install.jerry.company" | FENV_VERSION=vX.Y.Z bash

  instead of:

  $ curl -fsSL "https://fenv-install.jerry.company" | bash

• The available releases can be found from the release page.

$ fenv list-remote
# or
$ fenv install --list # or -l

$ fenv list
# or
$ fenv versions

fenv supports to install the specific version.

# Install 3.10.0
$ fenv install 3.10.0
# Install the latest version of 3.7.x at the moment. It may install 3.7.12
$ fenv install 3.7
# Install the latest version of 2.x.y at the moment. It may install 2.10.5
$ fenv install 2
$ fenv versions

fenv does not permit to run flutter upgrade, flutter downgrade, and flutter channel commands with the version Flutter SDK.

$ fenv local 3.10.0
$ fenv version
3.10.0 (set by `.../.flutter-version`)
$ flutter upgrade   # NG
fenv: `flutter upgrade` is not allowed. use `fenv install/uninstall` instead
$ flutter downgrade # NG
fenv: `flutter downgrade` is not allowed. use `fenv install/uninstall` instead
$ flutter channel   # NG
fenv: `flutter channel` is not allowed. use `fenv install/uninstall` instead

Nevertheless, you can execute those disallowed command like:

$ $FENV_ROOT/versions/3.10.0/bin/flutter upgrade

HOWEVER, DON'T DO THAT BECAUSE fenv REGARDS THOSE SDKS ARE POLLUTED.

fenv also supports to install the latest snapshot of dev, master, beta, and stable.

$ fenv install stable # or s
$ fenv versions

fenv permits to run flutter upgrade and flutter downgrade with the channel Flutter SDKs but not flutter channel command.

$ fenv local stable
$ fenv version
stable (set by `.../.flutter-version`)
$ flutter upgrade   # ok
...
$ flutter downgrade # ok
...
$ flutter channel   # NG
fenv: `flutter channel` is not allowed. use `fenv install/uninstall` instead

$ fenv global stable
# Let's check
$ fenv global
stable
$ fenv version
stable (set by `$FENV_ROOT/version`)
$ fenv which flutter
$FENV_ROOT/versions/stable/bin/flutter

After switching Flutter version, do flutter pub get in your workspace root to regenerate the .dart_tool/package_config.json file. For more information, see also here.

$ fenv global stable
$ cd my_dir
$ fenv local 3.10.0
# Let's check
$ fenv global
stable
$ fenv local
3.10.0
$ fenv version
3.10.0 (set by `.../my_dir/.flutter-version`)
$ cd more_deeper
$ fenv version
3.10.0 (set by `.../my_dir/.flutter-version`)
$ fenv which flutter
$FENV_ROOT/versions/3.10.0/bin/flutter

After switching Flutter version, do flutter pub get in your workspace root to regenerate the .dart_tool/package_config.json file. For more information, see also here.

$ fenv --help # or -h

For each command:

$ fenv completions --help
$ fenv versions --help

1. Remove the .flutter symlink from your Flutter workspace.

2. flutter doctor with the Flutter SDKs installed by fenv v0.0.x may show messages like:

   $ flutter doctor
   [✓] Flutter (Channel unknown, 3.0.0, on ...)

   or

   [!] Flutter (Channel unknown, 3.3.0, on ...)
      ! Flutter version 3.3.0 on channel unknown at $FENV_ROOT/versions/3.3.0
      ! Upstream repository unknown

   The Channel of Flutters, which was installed by fenv v0.0.x, are unknown.

   To make channels stable, please uninstall and reinstall them with fenv v0.1.x or later one. Then, you cannot see those warning message anymore.

3. For VS code users only: Remove dart.flutterSdkPath from settings.json If you previously specified the Flutter SDK path by dart.flutterSdkPath in settings.json whatever a user setting or a workspace setting.

• You can explicitly specify your shell with --shell option:

  $ $HOME/.fenv/bin/fenv init [--shell|-s] [bash|zsh|fish|ksh]
  $ $HOME/.fenv/bin/fenv init - [--shell|-s] [bash|zsh|fish|ksh]

  You can omit $HOME/.fenv/bin if you already add the path to your $PATH.

Run the following instruction:

$ fenv install

then, fenv will install the Flutter version specified in .flutter-version.

To find the locations of Dart SDK and Flutter SDK, Dart and Flutter plugins for IDEs such as Visual Studio Code and IntelliJ rely on some autogenerated files .dart_tool/package_config.json, which is generated by flutter pub get, and .idea/libraries/Dart_SDK.xml, which is generated by IntelliJ.

Therefore, to let those IDEs reload the SDKs after switching Flutter version, you need to run flutter pub get in your workspace root to regenerate the .dart_tool/package_config.json file.

$ cd workspace
$ fenv version
3.3.0 (set by `...`)
$ fenv local 3.10.0
$ fenv version
3.10.0 (set by `$FENV_ROOT/version`)

# If a Flutter version is switched, please do one of the followings:
$ flutter pub get  # in most cases, this might be fine.
$ melos bs         # if your project are managed by "melos".
$ fenv workspace . # if you are an IntelliJ IDEA's user. "." means the current directory

Unlike Visual Studio Code, IntelliJ's Dart plugin requires a little more step to find the correct Dart SDK path. If you are an IntelliJ IDEA' user or an Android Studio's user, you may need to run fenv workspace . to regenerate .idea/libraries/Dart_SDK.xml file as well as .dart_tool/package_config.json file.

If you were opening an IDE like Visual Studio Code and IntelliJ IDEA (including Android Studio), close and re-open it to let the IDE reload the Flutter SDK and the Dart SDK path.

Dart-based CLI tools, for example melos and vector_graphics_compiler, may show a warning like "Can't load Kernel binary: Invalid kernel binary format version." after switching Flutter SDK.

This is not the problem of fenv but a intrinsic problem of Dart-based CLI tools. You can do activate the CLI once more to suppress these warnings messages.

For example, you can re-activate melos like:

$ flutter pub global activate melos