Inspired by nvm
- Intro
- About
- Installing and Updating
- Usage
- Environment variables
- Bash Completion
- Compatibility Issues
- Uninstalling / Removal
- macOS Troubleshooting
- License
fvm
allows you to quickly install and use different versions of flutter via the command line.
Example:
$ fvm use 2.10.3
Now using flutter 2.10.3
$ flutter --version
Flutter 2.10.3 • channel stable • https://github.com/flutter/flutter.git
Framework • revision 7e9793dee1 (9 months ago) • 2022-03-02 11:23:12 -0600
Engine • revision bd539267b4
Tools • Dart 2.16.1 • DevTools 2.9.2
$ fvm install 3.3.8
Now 3.3.8 is installed
Simple as that!
fvm
is a version manager for flutter. fvm
works on any POSIX-compliant shell (sh, dash, ksh, zsh, bash), in particular on these platforms: unix, macOS, and windows WSL.
To install or update fvm, you should run the install script. To do that, you may either download and run the script manually, or use the following cURL or Wget command:
curl -o- https://raw.githubusercontent.com/fvm-sh/fvm/v0.5.1/install.sh | bash
wget -qO- https://raw.githubusercontent.com/fvm-sh/fvm/v0.5.1/install.sh | bash
Running either of the above commands downloads a script and runs it. The script clones the fvm repository to ~/.fvm
, and attempts to add the source lines from the snippet below to the correct profile file (~/.bash_profile
, ~/.zshrc
, ~/.profile
, or ~/.bashrc
).
export FVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.fvm" || printf %s "${XDG_CONFIG_HOME}/fvm")"
[ -s "$FVM_DIR/fvm.sh" ] && \. "$FVM_DIR/fvm.sh" # This loads fvm
-
If the environment variable
$XDG_CONFIG_HOME
is present, it will place thefvm
files there. -
You can add
--no-use
to the end of the above script (...fvm.sh --no-use
) to postpone usingfvm
until you manuallyuse
it. -
You can customize the install directory, profile using the
FVM_DIR
,PROFILE
. Eg:curl ... | FVM_DIR="path/to/fvm"
. Ensure that theFVM_DIR
does not contain a trailing slash. -
The installer can use
git
,curl
, orwget
to downloadfvm
, whichever is available.
On Linux, after running the install script, if you get fvm: command not found
or see no feedback from your terminal after you type command -v fvm
, simply close your current terminal, open a new terminal, and try verifying again.
Alternatively, you can run the following commands for the different shells on the command line:
bash: source ~/.bashrc
zsh: source ~/.zshrc
ksh: . ~/.profile
These should pick up the fvm
command.
Since OS X 10.9, /usr/bin/git
has been preset by Xcode command line tools, which means we can't properly detect if Git is installed or not. You need to manually install the Xcode command line tools before running the install script, otherwise, it'll fail.
If you get fvm: command not found
after running the install script, one of the following might be the reason:
-
Since macOS 10.15, the default shell is
zsh
and fvm will look for.zshrc
to update, none is installed by default. Create one withtouch ~/.zshrc
and run the install script again. -
If you use bash, the previous default shell, your system may not have
.bash_profile
or.bashrc
files where the command is set up. Create one of them withtouch ~/.bash_profile
ortouch ~/.bashrc
and run the install script again. Then, run. ~/.bash_profile
or. ~/.bashrc
to pick up thefvm
command. -
You have previously used
bash
, but you havezsh
installed. You need to manually add these lines to~/.zshrc
and run. ~/.zshrc
. -
You might need to restart your terminal instance or run
. ~/.fvm/fvm.sh
. Restarting your terminal/opening a new tab/window, or running the source command will load the command and the new configuration. -
If the above didn't help, you might need to restart your terminal instance. Try opening a new tab/window in your terminal and retry.
If the above doesn't fix the problem, you may try the following:
-
If you use bash, it may be that your
.bash_profile
(or~/.profile
) does not source your~/.bashrc
properly. You could fix this by addingsource ~/<your_profile_file>
to it or follow the next step below. -
Try adding the snippet from the install section, that finds the correct fvm directory and loads fvm, to your usual profile (
~/.bash_profile
,~/.zshrc
,~/.profile
, or~/.bashrc
).
Note For Macs with the M1 chip, flutter started offering arm64 arch darwin archive at stable channel since version 3.0.0 and beta channel since 2.12.0-4.1.pre. If you are facing issues installing flutter using fvm
, you may want to update to one of those versions or later.
To verify that fvm has been installed, do:
command -v fvm
which should output fvm
if the installation was successful. Please note that which fvm
will not work, since fvm
is a sourced shell function, not an executable binary.
Note: On Linux, after running the install script, if you get fvm: command not found
or see no feedback from your terminal after you type command -v fvm
, simply close your current terminal, open a new terminal, and try verifying again.
Note: fvm
also support Windows in some cases. It should work through WSL (Windows Subsystem for Linux) depending on the version of WSL. It should also work with GitBash (MSYS) or Cygwin.
Note: On OS X, if you do not have Xcode installed and you do not wish to download the ~4.3GB file, you can install the Command Line Tools
. You can check out this blog post on how to just that:
Homebrew installation is not supported. If you have issues with homebrew-installed fvm
, please brew uninstall
it, and install it using the instructions below, before filing an issue.
If you have git
installed (requires git v1.7.10+):
- clone this repo in the root of your user profile
cd ~/
from anywhere thengit clone https://github.com/fvm-sh/fvm.git .fvm
cd ~/.fvm
and check out the latest version withgit checkout v0.5.1
- activate
fvm
by sourcing it from your shell:. ./fvm.sh
Now add these lines to your ~/.bashrc
, ~/.profile
, or ~/.zshrc
file to have it automatically sourced upon login:
(you may have to add to more than one of the above files)
export FVM_DIR="$HOME/.fvm"
[ -s "$FVM_DIR/fvm.sh" ] && \. "$FVM_DIR/fvm.sh" # This loads fvm
[ -s "$FVM_DIR/bash_completion" ] && \. "$FVM_DIR/bash_completion" # This loads fvm bash_completion
For a fully manual install, execute the following lines to first clone the fvm
repository into $HOME/.fvm
, and then load fvm
:
export FVM_DIR="$HOME/.fvm" && (
git clone https://github.com/fvm-sh/fvm.git "$FVM_DIR"
cd "$FVM_DIR"
git checkout `git describe --abbrev=0 --tags --match "v[0-9]*" $(git rev-list --tags --max-count=1)`
) && \. "$FVM_DIR/fvm.sh"
Now add these lines to your ~/.bashrc
, ~/.profile
, or ~/.zshrc
file to have it automatically sourced upon login:
(you may have to add to more than one of the above files)
export FVM_DIR="$HOME/.fvm"
[ -s "$FVM_DIR/fvm.sh" ] && \. "$FVM_DIR/fvm.sh" # This loads fvm
[ -s "$FVM_DIR/bash_completion" ] && \. "$FVM_DIR/bash_completion" # This loads fvm bash_completion
For manual upgrade with git
(requires git v1.7.10+):
- change to the
$FVM_DIR
- pull down the latest changes
- check out the latest version
- activate the new version
(
cd "$FVM_DIR"
git fetch --tags origin
git checkout `git describe --abbrev=0 --tags --match "v[0-9]*" $(git rev-list --tags --max-count=1)`
) && \. "$FVM_DIR/fvm.sh"
To install a specific version of flutter:
fvm install 3.3.8 # or 3.0.5, 2.5.3, etc
You can list available versions using ls-remote
:
fvm ls-remote
And then in any new shell just use the installed version:
fvm use 3.3.8
If you want to use the system-installed version of flutter, you can use the special alias "system":
fvm use system
If you want to see what versions are installed:
fvm ls
If you want to see what versions are available to install:
fvm ls-remote
To restore your PATH, you can deactivate it:
fvm deactivate
To use a mirror of the flutter archives, set $FLUTTER_STORAGE_BASE_URL
:
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
fvm install 3.3.8
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn fvm install 3.3.8
IDEs usually need flutter sdk path to provide services, you can create a soft link to a version by fvm link <version>
:
fvm link 3.3.8
This will link installed 3.3.8 version path to .fvm/flutter
under current directory.
Then you can config IDEs (like VS Code) with this soft link:
.vscode/settings.json
{
"dart.flutterSdkPath": ".fvm/flutter",
}
fvm exposes the following environment variables:
FVM_DIR
- fvm's installation directory.
Additionally, fvm modifies PATH
, and, if present, MANPATH
when changing versions.
To activate, you need to source bash_completion
:
[[ -r $FVM_DIR/bash_completion ]] && \. $FVM_DIR/bash_completion
Put the above sourcing line just below the sourcing line for fvm in your profile (.bashrc
, .bash_profile
).
fvm:
$ fvm
Tab
install list-remote uninstall ls unload current help list ls-remote use
fvm use:
$ fvm use
Tab
3.3.8 3.0.5 2.10.3
fvm uninstall:
$ fvm uninstall
Tab
3.3.8 3.0.5 2.10.3
The following are known to cause issues:
Shell settings:
set -e
To remove fvm
manually, execute the following:
$ rm -rf "$FVM_DIR"
Edit ~/.bashrc
(or other shell resource config) and remove the lines below:
export FVM_DIR="$HOME/.fvm"
[ -s "$FVM_DIR/fvm.sh" ] && \. "$FVM_DIR/fvm.sh" # This loads fvm
[[ -r $FVM_DIR/bash_completion ]] && \. $FVM_DIR/bash_completion
fvm flutter version not found in vim shell
If you set flutter version to a version other than your system flutter version fvm use 3.3.8
and open vim and run :!flutter --version
you should see 3.3.8
if you see your system version 2.10.3
. You need to run:
sudo chmod ugo-x /usr/libexec/path_helper
More on this issue in dotphiles/dotzsh.
There is one more edge case causing this issue, and that's a mismatch between the $HOME
path and the user's home directory's actual name.
You have to make sure that the user directory name in $HOME
and the user directory name you'd see from running ls /Users/
are capitalized the same way
To change the user directory and/or account name follow the instructions here
Homebrew makes zsh directories unsecure
zsh compinit: insecure directories, run compaudit for list.
Ignore insecure directories and continue [y] or abort compinit [n]? y
Homebrew causes insecure directories like /usr/local/share/zsh/site-functions
and /usr/local/share/zsh
. This is not an fvm
problem - it is a homebrew problem. Refer here for some solutions related to the issue.
See LICENSE.