Custom Flutter Version (Forks)

In case you need to have a custom version of the Flutter SDK (a fork), referenced within a project, and you want to continue to use FVM, you can do so by following the steps below.

There are two ways to use a custom version of the Flutter SDK:

Clone the fork within the FVM cache

This method is useful if you want to use a fork of the Flutter SDK within a project and reference that "custom" version like you would releases or channels.

1. Look for the path where FVM caches the versions. You can find this path by running the following command:

fvm list

Output:

Cache directory:  /Users/{user}/fvm/versions
Directory Size: 6.47 GB
 
┌────────────────┬─────────┬────────────────────┬─────────────────┬──────────────┬────────┬───────┐
│ Version        │ Channel │ Flutter Version    │ Dart Version    │ Release Date │ Global │ Local │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ stable         │ stable  │ 3.24.1             │ 3.5.1           │ Aug 21, 2024 │        │       │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ 3.19.0         │ stable  │ 3.19.0             │ 3.3.0           │ Feb 15, 2024 │        │       │
└────────────────┴─────────┴────────────────────┴─────────────────┴──────────────┴────────┴───────┘

2. Clone the fork of the Flutter SDK into the cache directory.

When cloning, make sure to prefix the version with custom_ and then add the name of the version. For example, if you want to fork a version called special, you will have to clone it into the cache directory as custom_special.

The prefix custom_ is used to differentiate the custom versions from the official Flutter versions and allows FVM to not apply the same level of validation as it does with the official versions.

Now, when you run fvm list, you should see the custom version in the list.

Output:

Cache directory:  /Users/{user}/fvm/versions
Directory Size: 6.47 GB
 
┌────────────────┬─────────┬────────────────────┬─────────────────┬──────────────┬────────┬───────┐
│ Version        │ Channel │ Flutter Version    │ Dart Version    │ Release Date │ Global │ Local │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ custom_special │         │ 3.24.0-1.0.pre.575 │ 3.6.0-146.0.dev │              │        │       │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ stable         │ stable  │ 3.24.1             │ 3.5.1           │ Aug 21, 2024 │        │       │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ 3.19.0         │ stable  │ 3.19.0             │ 3.3.0           │ Feb 15, 2024 │        │       │
└────────────────┴─────────┴────────────────────┴─────────────────┴──────────────┴────────┴───────┘

3. Use the custom version within your project.

You can now use the custom version within your project by running the following command, but referencing it as custom_special:

fvm use custom_special

Change the repository URL to the fork

With FVM, you can also change the repository URL to the fork you want to use. This method is useful if you want to use a fork of the Flutter SDK globally and want to continue to reference releases and channels from the fork version.

There are a few ways you can do this:

Option 1. Change the repository URL globally used by FVM

fvm config --flutter-url https://github.com/org/custom-flutter.git

Now, when you run fvm install or fvm use, it will use the custom repository URL.

Option 2. Change the environment variable

You can also change the repository URL by setting the environment variable FVM_FLUTTER_URL:

# Change the env var in your shell profile
export FVM_FLUTTER_URL="https://github.com/org/custom-flutter.git"

Setting the custom repository URL per project

You can also set the custom repository URL per project by creating a .fvmrc file in the root of your project and adding the following:

{
  "flutterUrl": "https://github.com/org/custom-flutter.git"
}