fvm Documentation

1. Project Overview & Quickstart (leoafarias/fvm) Copy Chapter

File: README.md Copy Chapter

fvm

FVM manages Flutter SDK versions per project. Switch between Flutter versions instantly without reinstalling, making it easy to test new releases and maintain consistent builds across your team.

Why FVM? Copy Chapter

• Need for simultaneous use of multiple Flutter SDKs.
• SDK testing requires constant channel switching.
• Channel switches are slow and need repeated reinstalls.
• Difficulty managing the latest successful SDK version used in an app.
• Flutter's major updates demand total app migration.
• Inconsistencies occur in development environments within teams.

For more information, read the Getting Started guide.

Release Process (For Maintainers) Copy Chapter

FVM uses GitHub releases to trigger automated deployments across all platforms:

Creating a New Release Copy Section

1. Ensure main branch is ready

   • All changes merged and tested
   • Version will be set automatically from release tag

2. Create GitHub Release

   • Go to GitHub Releases
   • Click "Create a new release"
   • Choose tag: v4.0.0-beta.2 (follows semver with 'v' prefix)
   • Write release notes in GitHub editor
   • Click "Publish release"

3. Automated Deployment

   • release.yml triggers automatically
   • Deploys to: pub.dev, GitHub binaries, Homebrew, Chocolatey, Docker
   • Monitor progress in Actions tab

Dart SDK requirements: Day-to-day development now targets the
repository SDK constraint (>=3.6.0 <4.0.0). Release automation lives under
tool/release_tool/ and requires Dart SDK >=3.8.0. CI pins this higher tool
chain via the RELEASE_DART_SDK environment variable (currently 3.9.0) so
it matches the versions packaged for Homebrew and other installers.
If you run release tasks locally, switch to a Dart SDK 3.8.0 or newer
before executing commands from tool/release_tool/.

Emergency Releases Copy Section

For hotfixes or emergency releases:

1. Update version manually in pubspec.yaml
2. Use individual platform workflows via manual dispatch:
   • deploy_homebrew.yml for Homebrew updates
   • deploy_docker.yml for Docker deployment
   • Individual platform deployments as needed

For complete emergency deployment, create a GitHub release as normal.

See Workflow Documentation for detailed information.

Contributors Copy Chapter

Checkout Flutter Sidekick. Read more about it here.

Troubleshooting Copy Chapter

Please view our FAQ.

License Copy Chapter

This project is licensed under the MIT License; see LICENSE file for details.

File: docs/pages/documentation/advanced/custom-version.mdx Copy Chapter

title: Custom Flutter SDK (Forks) Copy Chapter

import { Callout } from "nextra/components";

Custom Flutter Version (Forks)

FVM supports using custom Flutter SDK versions from forked repositories. This is useful when you need a modified version of Flutter.

Using the Fork Command (Recommended) Copy Chapter

The simplest way is to use the fork command:

# Add a fork
fvm fork add mycompany https://github.com/mycompany/flutter.git

# Use it like any version
fvm install mycompany/stable
fvm use mycompany/3.19.0

For more details, see the fork command documentation.

Alternative Methods Copy Chapter

**Clone the fork within the FVM cache** Copy Chapter

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.

Make sure you always clone the whole repository using the command git clone url-to-repository.git.
Do not use --depth or --single-branch as it might cause issues with the Flutter SDK.
Flutter Tools depends on repository references to determine its version correct version.

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** Copy Chapter

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** Copy Section

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"
}

File: docs/pages/documentation/advanced/json-api.md Copy Chapter

JSON API

FVM provides JSON API endpoints for integrating with other tools. All commands support the --compress option for compact output.

Commands Copy Chapter

list Copy Section

Lists installed Flutter SDK versions.

fvm api list [--compress] [--skip-size-calculation]

Options:

• --compress - Compact JSON output
• --skip-size-calculation - Skip cache size calculation

releases Copy Section

Shows available Flutter releases.

fvm api releases [--compress] [--limit <n>] [--filter-channel <channel>]

Options:

• --compress - Compact JSON output
• --limit - Number of releases to return
• --filter-channel - Filter by channel (stable, beta, dev)

context Copy Section

Returns FVM environment information.

fvm api context [--compress]

project Copy Section

Returns project configuration.

fvm api project [--compress] [--path ]

Options:

• --compress - Compact JSON output
• --path - Project directory path

Integration Example Copy Chapter

# Get current project version
fvm api project --compress | jq -r '.project.pinnedVersion'

# List installed versions
fvm api list --compress | jq -r '.versions[].name'

`list` Copy Section

Lists the installed Flutter SDK versions available locally.

Usage:

fvm api list [options]

Options:

• --compress (-c): Outputs JSON with no whitespace.
• --skip-size-calculation (-s): Skips calculating the size of cached versions.

Response Payload:

{
  "size": "922.50 MB",
  "versions": [
    {
      "name": "3.19.0",
      "directory": "/path/to/fvm/versions/3.19.0",
      "releaseFromChannel": null,
      "type": "release",
      "binPath": "/path/to/fvm/versions/3.19.0/bin",
      "hasOldBinPath": false,
      "dartBinPath": "/path/to/fvm/versions/3.19.0/bin",
      "dartExec": "/path/to/fvm/versions/3.19.0/bin/dart",
      "flutterExec": "/path/to/fvm/versions/3.19.0/bin/flutter",
      "flutterSdkVersion": "3.19.0",
      "dartSdkVersion": "3.5.1",
      "isSetup": true
    },
    ...
  ]
}

`releases` Copy Section

Provides a list of available Flutter SDK releases.

Usage:

fvm api releases [options]

Options:

• --compress: Outputs JSON with no whitespace.
• --limit [number]: Limits the number of releases listed.
• --filter-channel [channel]: Filters the releases by channel. Available channels are stable, beta, and dev.

Response Payload:

{
  "versions": [
    ...
    {
      "hash": "0b591f2c82e9f59276ed68c7d4cbd63196f7c865",
      "channel": "beta",
      "version": "3.17.0-0.0.pre",
      "release_date": "2023-11-15T22:44:50.703003Z",
      "archive": "beta/macos/flutter_macos_3.17.0-0.0.pre-beta.zip",
      "sha256": "2937447f814eff2ebf5aba098dfdb059654a0113456f1b22e855403c2ec413df",
      "dart_sdk_arch": "x64",
      "dart_sdk_version": "3.3.0 (build 3.3.0-91.0.dev)",
      "active_channel": false,
      "channelName": "beta",
      "archiveUrl": "https://storage.googleapis.com/flutter_infra_release/releases/beta/macos/flutter_macos_3.17.0-0.0.pre-beta.zip"
    }
  ],
  "channels": {
    "beta": {...},
    "stable": {...}
  }
}

`context` Copy Section

Returns information about the FVM's current context.

Usage:

fvm api context [options]

Options:

• --compress: Outputs JSON with no whitespace.

Response Payload:

{
  "context": {
    "fvmVersion": "3.0.14",
    "workingDirectory": "/path/to/project",
    "isTest": false,
    "fvmDir": "/path/to/.fvm",
    "gitCache": true,
    "runPubGetOnSdkChanges": true,
    "gitCachePath": "/path/to/.fvm/cache.git",
    "flutterUrl": "https://github.com/flutter/flutter.git",
    "lastUpdateCheck": "2024-03-13T14:46:08.735250Z",
    "updateCheckDisabled": false,
    "privilegedAccess": false,
    "globalCacheLink": "/path/to/.fvm/default",
    "globalCacheBinPath": "/path/to/.fvm/default/bin",
    "versionsCachePath": "/path/to/.fvm/versions",
    "configPath": "/Users/username/Library/Application Support/fvm/.fvmrc",
    "isCI": false,
    "id": "MAIN",
    "args": [
      "api",
      "info"
    ]
  }
}

`project` Copy Section

Fetches details about the current Flutter project configuration.

Usage:

fvm api project [options]

Options:

• --compress: Outputs JSON with no whitespace.
• --path [path]: The path to the project. Defaults to the current working directory.

Response Payload:

{
  "project": {
    "name": "my_project",
    "config": {
      "flutter": "3.19.0",
      "flavors": {
        "production": "3.19.0",
        "development": "stable"
      }
    },
    "path": "/path/to/project",
    "pinnedVersion": {
      "name": "3.19.0",
      "releaseFromChannel": null,
      "type": "release"
    },
    "activeFlavor": "production",
    "flavors": {
      "production": "3.19.0",
      "development": "stable"
    },
    "dartToolGeneratorVersion": "3.3.0",
    "dartToolVersion": "3.19.0",
    "isFlutter": true,
    "localFvmPath": "/path/to/project/.fvm",
    "localVersionsCachePath": "/path/to/project/.fvm/versions",
    "localVersionSymlinkPath": "/path/to/project/.fvm/versions/3.19.0",
    "gitIgnorePath": "/path/to/project/.gitignore",
    "pubspecPath": "/path/to/project/pubspec.yaml",
    "configPath": "/path/to/project/.fvmrc",
    "legacyConfigPath": "/path/to/project/.fvm/fvm_config.json",
    "hasConfig": true,
    "hasPubspec": true,
    "pubspec": {
      "name": "my_project",
      "version": "0.1.0",
      "publish_to": "none",
      "environment": {
        "sdk": ">=2.17.0 <4.0.0"
      },
      "description": "A new Flutter project.",
      "dependencies": {
        ...
      },
      "dev_dependencies": {
        ...
      },
      "flutter": {
        "uses-material-design": true
      }
    }
  }
}

File: docs/pages/documentation/advanced/release-multiple-channels.md Copy Chapter

id: release_multiple_channels title: Release In Multiple Channels Copy Chapter

Release In Multiple Channels

Sometimes a Flutter version exists in multiple channels. FVM prioritizes the most stable channel: stable > beta > dev.

Example Copy Chapter

Version 3.16.0 exists in both stable and beta channels:

# Installs from stable channel (default)
fvm use 3.16.0

Force Specific Channel Copy Chapter

To install from a specific channel, use @channel:

# Install from beta channel
fvm use 3.16.0@beta

File: docs/pages/documentation/getting-started/configuration.mdx Copy Chapter

id: configuration title: Configuration Copy Chapter

import { Callout } from "nextra/components";
import { FileTree } from "nextra/components";

Configuration

Configure FVM and IDEs for better support for different development environments.

Project Copy Chapter

There are two main parts for a project that has FVM configured: the .fvmrc config file and the .fvm directory.

Config File `.fvmrc` Copy Section

This contains the version linked to the project. This file is automatically created when you run fvm use {version}. Here you can also find project-specific settings and flavors.

{
  "flutter": "3.19.0",
  "flavors": {
    "development": "beta",
    "production": "3.19.0"
  },
  "updateVscodeSettings": true,
  "updateGitIgnore": true,
  "runPubGetOnSdkChanges": true
}

• flutter: The version of the Flutter SDK to be used, falling back to the flutter value if not explicitly set.
• cachePath: Defines the path to the project's cache directory.
• useGitCache: (default: true) Indicates whether the Git cache is used for dependencies.
• gitCachePath: Sets the path to the Git cache directory, applicable if useGitCache is true.
• flutterUrl: Specifies the URL to the Flutter SDK repository.
• privilegedAccess: (default: true) Determines if configurations requiring elevated permissions are enabled.
• flavors: A map defining custom project flavors for different configurations.
• updateVscodeSettings: (default: true) Flags whether to auto-update VS Code settings on configuration changes.
• updateGitIgnore: (default: true) Indicates whether to auto-update the .gitignore file based on project configurations.
• updateMelosSettings: (default: true) Indicates whether to auto-update Melos configuration files.
• runPubGetOnSdkChanges: (default: true) Triggers flutter pub get automatically upon Flutter SDK version changes.

.fvm Directory Copy Section

Inside the directory, you will find the following files and symlinks:

• flutter_sdk - Symlink to the Flutter SDK version linked to the project (points to the cached version).
• fvm_config.json - (deprecated) Legacy configuration file for backward compatibility.
• release - (internal use only) File containing the release version of FVM.
• version - (internal use only) File containing the version of FVM that created this configuration.

Environment Variables Copy Chapter

Set environment variables at the system level to apply configurations globally. These are typically used for settings that remain constant across multiple projects or runtime environments.

Supported Environment Variables: Copy Chapter

• FVM_CACHE_PATH: Specifies the cache path for Flutter versions.
• FVM_USE_GIT_CACHE: Enables/disables the git cache globally (true/false).
• FVM_GIT_CACHE_PATH: Sets the path for the local git reference cache.
• FVM_FLUTTER_URL: Defines the Flutter repository git URL.

Legacy and Deprecated Variables: Copy Section

• FVM_HOME: ⚠️ Legacy - Use FVM_CACHE_PATH instead. Still supported as fallback for backward compatibility.
• FVM_GIT_CACHE: ❌ Deprecated - Use FVM_FLUTTER_URL instead. No longer supported.

File: docs/pages/documentation/getting-started/faq.md Copy Chapter

id: faq title: FAQ Copy Chapter

FAQ

Upgrade Flutter Channel Copy Chapter

As described in our Principles, FVM does not override standard Flutter behavior. Therefore, to upgrade a channel, you will have to use the standard flutter upgrade. You can find more about it in the Running Flutter section.

flutter and dart commands not found Copy Chapter

If fvm flutter or fvm dart commands are not working:

1. Make sure FVM is properly installed and in your PATH
2. Ensure you have a Flutter version configured in your project (fvm use <version>)
3. Check that the .fvm directory exists in your project

How does FVM find the Flutter version to use? Copy Chapter

FVM searches for the Flutter SDK in this order:

1. Project .fvmrc file
2. Ancestor directory .fvmrc files
3. Global version (set with fvm global)
4. System PATH Flutter installation

Cannot install the latest version of FVM Copy Chapter

When running dart pub global activate fvm, pub will grab the latest FVM version that is compatible with the installed dart-sdk. Upgrade to the latest version of Dart, and run the command again. Go to get dart for more information.

How to uninstall FVM Copy Chapter

Install script (macOS/Linux):

./install.sh --uninstall

Homebrew:

brew uninstall fvm

Pub:

dart pub global deactivate fvm

Chocolatey (Windows):

choco uninstall fvm

Remove cached Flutter versions (optional):

fvm destroy

Commands run twice on Windows Copy Chapter

This happens due to a pub issue dart-lang:2934. To avoid this issue from happening, make sure your PATH is in the following order. Please read the following.

Invalid kernel binary or invalid SDK hash when running FVM Copy Chapter

There are a few reasons this can happen. However, it means that the FVM snapshot is not compatible with the Dart version that is installed.

Please do the following:

1. On Windows, make sure your environment variables are in the following order as described here.
2. Run dart pub global deactivate fvm.
3. Run dart pub global activate fvm.

Command 'pub' not found Copy Chapter

If you get Command 'pub' not found, then make sure to append export PATH="$PATH:/usr/lib/dart/bin" to your ~/.bashrc (gets reinitiated each time you open a bash shell) or ~/.profile (only read at login) file.

Environment variables order for Windows in PATH Copy Chapter

Flutter comes with Dart embedded. Because of that, you can find some conflicts when running standalone Dart and Flutter together. Here is a suggestion of what we found to be the correct order of dependencies to avoid issues.

1. Pub Cache for global packages
2. Dart SDK (if installed outside of Flutter)
3. Flutter SDK

It should look like this:

C:\Users\\AppData\Roaming\Pub\Cache\bin
C:\src\flutter\bin\cache\dart-sdk\bin
C:\src\flutter\bin

Git not found after install on Windows Copy Chapter

If you see this error even though git --version works, Git 2.35.2+ is blocking the Flutter cache directory. Follow the detailed steps in the Git Safe Directory troubleshooting guide.

Quick fix:

git config --global --add safe.directory "*"

Restart your terminal and IDE afterward. The guide also covers locking the setting down to specific FVM folders if you prefer a narrower scope.

File: docs/pages/documentation/getting-started/installation.mdx Copy Chapter

id: installation title: Installation Copy Chapter

import { Tabs, Callout } from "nextra/components";

Installation

There are several ways to install FVM. Choose the method that best fits your development environment.

Recommendation Copy Chapter

We recommend installing the Flutter SDK globally using the official installation guide here. This will be the main version of Flutter across your machine.

Use FVM to manage the Flutter SDK version for your projects.

You can download the standalone packages from the GitHub repo here.

<Tabs items={['macOS', 'Windows', 'Linux', 'Pub']}>
<Tabs.Tab>

Install Script (Recommended) Copy Chapter

Install the latest version:

curl -fsSL https://fvm.app/install.sh | bash

Install a specific version:

curl -fsSL https://fvm.app/install.sh | bash -s -- <version>

Replace <version> with your desired FVM version (e.g., 3.2.1)

Homebrew Copy Chapter

Install:

brew install fvm

Uninstall:

brew uninstall fvm

</Tabs.Tab>
<Tabs.Tab>

Chocolatey Copy Chapter

Install FVM using Chocolatey from the command line or PowerShell:

choco install fvm

Uninstall:

choco uninstall fvm

Standalone Archive Copy Chapter

Native Windows builds are published on the GitHub Releases page.
Download the windows-x64 or windows-arm64 zip for your device, extract it, and add the extracted fvm directory to your PATH.

</Tabs.Tab>

<Tabs.Tab>

Install Script (Recommended) Copy Chapter

Install the latest version:

curl -fsSL https://fvm.app/install.sh | bash

Install a specific version:

curl -fsSL https://fvm.app/install.sh | bash -s -- <version>

Replace <version> with your desired FVM version (e.g., 3.2.1)

Alternative Installation Copy Chapter

For alternative installation methods, see the GitHub Releases page.

</Tabs.Tab>

<Tabs.Tab>
You can also install FVM as a pub package.

dart pub global activate fvm

Uninstall:

dart pub global deactivate fvm

</Tabs.Tab>

Installation Options Copy Chapter

Install Script Features Copy Section

The install script (install.sh) supports several options:

• Latest version: curl -fsSL https://fvm.app/install.sh | bash
• Specific version: curl -fsSL https://fvm.app/install.sh | bash -s -- <version> (replace <version> with desired FVM version)
• Custom install location: FVM_INSTALL_DIR= curl -fsSL https://fvm.app/install.sh | bash (absolute path under $HOME)
• Help: ./install.sh --help
• Version info: ./install.sh --version

Supported Platforms Copy Section

Requirements Copy Section

• macOS/Linux: curl and tar
• Windows: PowerShell and Chocolatey for Chocolatey installs, or a standalone zip from GitHub Releases

PATH Configuration Copy Chapter

The install script prints instructions to add FVM to your shell PATH. For manual installations, add FVM to your PATH:

<Tabs items={['macOS/Linux (Install Script)', 'macOS/Linux (Pub)', 'Windows']}>
<Tabs.Tab>
The install script prints instructions to add FVM to your PATH. Add the following to your shell configuration:

• Bash: Add to ~/.bashrc
• Zsh: Add to ~/.zshrc
• Fish: Run fish_add_path "/bin"

Add this line: export PATH="/bin:$PATH" (default install dir is $HOME/fvm)

To apply changes immediately: source ~/.zshrc (or your shell config file)

</Tabs.Tab>
<Tabs.Tab>
For pub installations, add to your shell profile:

export PATH="$PATH:$HOME/.pub-cache/bin"

</Tabs.Tab>
<Tabs.Tab>
Add to your PATH environment variable:

%USERPROFILE%\AppData\Local\Pub\Cache\bin

</Tabs.Tab>

Uninstallation Copy Chapter

Install Script:

curl -fsSL https://fvm.app/install.sh | bash -s -- --uninstall

Homebrew:

brew uninstall fvm

Chocolatey:

choco uninstall fvm

Pub:

dart pub global deactivate fvm

Remove cached Flutter versions (optional):

fvm destroy

File: docs/pages/documentation/guides/basic-commands.mdx Copy Chapter

id: basic_commands title: Commands Reference Copy Chapter

import { Cards, Card } from "nextra/components";
import {
DeviceFloppyIcon,
DownloadIcon,
TrashIcon,
TerminalIcon,
GlobeIcon,
ListIcon,
EyeIcon,
ArrowRightOnRectangleIcon,
PlayIcon,
} from "@radix-ui/react-icons";

Commands Reference

Complete reference for FVM commands to manage Flutter SDK versions efficiently.

use Copy Chapter

Sets a Flutter SDK version for the current project. Creates project configuration and ensures environment consistency.

fvm use [version] [options]

Arguments Copy Section

• version - Flutter SDK version, channel, or commit hash (optional)
  • If omitted, checks project configuration or prompts for selection
  • Examples: 3.19.0, stable, fa345b1

Options Copy Section

• -f, --force - Bypasses Flutter project validation checks
• -p, --pin - Pins the latest release of a channel (not for master)
• --flavor <name>, --env <name> - Sets version for a specific project flavor
• -s, --skip-setup - Skips SDK setup after installation
• --skip-pub-get - Skips dependency resolution after switching

Examples Copy Section

# Set specific version
fvm use 3.19.0

# Pin latest stable release
fvm use stable --pin

# Set version for production flavor
fvm use 3.19.0 --flavor production

# Use a specific commit
fvm use fa345b1

What happens Copy Section

1. Downloads SDK if not cached
2. Creates .fvm directory with SDK symlink
3. Updates .fvmrc configuration
4. Configures IDE settings (VS Code)
5. Runs flutter pub get (unless skipped)

install Copy Chapter

Downloads and caches a Flutter SDK version for future use. Runs setup by default to ensure SDK is ready to use.

fvm install [version] [options]

Arguments Copy Section

• version - Flutter SDK version to install (optional)
  • If omitted, installs version from project configuration

Options Copy Section

• -s, --setup - Downloads SDK dependencies after install (default: true)
• --no-setup - Skip downloading SDK dependencies for faster caching
• --skip-pub-get - Skips dependency resolution

Aliases Copy Section

• fvm i - Short form

Examples Copy Section

# Install with setup (default behavior)
fvm install 3.19.0

# Skip setup for faster caching
fvm install 3.19.0 --no-setup

# Install from project config
fvm install

list Copy Chapter

Displays all installed Flutter SDK versions.

fvm list

Aliases Copy Section

• fvm ls - Short form

Output Copy Section

Shows all cached SDK versions with their installation paths.

releases Copy Chapter

Shows available Flutter SDK releases for installation.

fvm releases [options]

Options Copy Section

• -c, --channel <name> - Filter by channel: stable, beta, dev, all (default: stable)

Examples Copy Section

# Show stable releases
fvm releases

# Show beta channel releases
fvm releases --channel beta

# Show all releases
fvm releases --channel all

remove Copy Chapter

Removes Flutter SDK versions from cache.

fvm remove [version] [options]

Arguments Copy Section

• version - SDK version to remove (prompts if omitted)

Options Copy Section

• -a, --all - Removes all cached versions

Examples Copy Section

# Remove specific version
fvm remove 3.19.0

# Remove all versions
fvm remove --all

global Copy Chapter

Sets a default Flutter SDK version for the system.

fvm global [version]

Arguments Copy Section

• version - SDK version to set as global

Options Copy Section

• -f, --force - Bypasses SDK validation
• -u, --unlink - Removes global version setting

Examples Copy Section

# Set global version
fvm global 3.19.0

# Remove global version
fvm global --unlink

spawn Copy Chapter

Runs Flutter commands with a specific SDK version.

fvm spawn <version> <flutter_command> [args...]

Arguments Copy Section

• version - SDK version to use (required)
• flutter_command - Flutter command to execute
• args - Additional command arguments

Examples Copy Section

# Build with specific version
fvm spawn 3.19.0 build apk

# Run tests with different version
fvm spawn 3.16.0 test

exec Copy Chapter

Executes commands using the project's configured Flutter SDK.

fvm exec <command> [args...]

Arguments Copy Section

• command - Command to execute
• args - Command arguments

Examples Copy Section

# Run melos with project SDK
fvm exec melos bootstrap

# Execute custom script
fvm exec ./scripts/build.sh

flutter Copy Chapter

Runs Flutter commands using the project's configured SDK.

fvm flutter <command> [args...]

Arguments Copy Section

• command - Flutter command to run
• args - Command arguments

Examples Copy Section

# Common Flutter commands
fvm flutter doctor
fvm flutter build apk
fvm flutter test
fvm flutter run

Note Copy Section

Prevents flutter upgrade on release versions. Use channels for upgrades.

dart Copy Chapter

Runs Dart commands using the project's configured SDK.

fvm dart <command> [args...]

Arguments Copy Section

• command - Dart command to run
• args - Command arguments

Examples Copy Section

# Common Dart commands
fvm dart pub get
fvm dart analyze
fvm dart format .
fvm dart run build_runner build

destroy Copy Chapter

Removes the entire FVM cache and all installed versions.

fvm destroy [options]

Options Copy Section

• -f, --force - Bypasses confirmation prompt (use with caution)

Examples Copy Section

# Remove cache with confirmation prompt
fvm destroy

# Remove cache without confirmation (dangerous)
fvm destroy --force

Warning Copy Section

This action is irreversible and removes all cached Flutter SDKs.

flavor Copy Chapter

Executes Flutter commands using a flavor-specific SDK version.

fvm flavor <flavor> <flutter_command> [args...]

Arguments Copy Section

• flavor - Project flavor name
• flutter_command - Flutter command to execute
• args - Command arguments

Examples Copy Section

# Build with development flavor
fvm flavor development build apk

# Test with staging flavor
fvm flavor staging test

fork Copy Chapter

Manages Flutter fork aliases for custom repositories.

Subcommands Copy Section

fork add

Adds a fork alias for a custom Flutter repository.

fvm fork add <alias>

Arguments:

• alias - Short name for the fork
• url - Git repository URL (must end with .git)

Example:

fvm fork add mycompany https://github.com/mycompany/flutter.git

fork remove

Removes a fork alias.

fvm fork remove <alias>

Example:

fvm fork remove mycompany

fork list

Shows all configured fork aliases.

fvm fork list

Using forks Copy Section

After adding a fork, use it with any version:

# Install fork version
fvm install mycompany/stable
fvm install mycompany/3.19.0

# Use fork version
fvm use mycompany/stable

config Copy Chapter

Manages global FVM settings.

fvm config [options]

Options Copy Section

• --cache-path - Sets custom cache directory
• --flutter-url - Sets Flutter repository URL
• --use-git-cache - Enables Git cache for faster installs (default: true)
• --no-use-git-cache - Disables Git cache
• --git-cache-path - Sets Git cache directory
• --update-check - Enables FVM update notifications (default: true)
• --no-update-check - Disables update notifications

Examples Copy Section

# View current configuration
fvm config

# Set custom cache location
fvm config --cache-path ~/custom/flutter/cache

# Disable update checks
fvm config --no-update-check

# Use custom Flutter repository
fvm config --flutter-url https://github.com/mycompany/flutter.git

doctor Copy Chapter

Shows detailed FVM environment information and diagnostics.

fvm doctor

Output includes Copy Section

• Project configuration
• IDE integration status
• Environment details
• Path validation
• FVM version

Useful for troubleshooting configuration issues.

api Copy Chapter

Provides JSON output for integration with other tools.

Common options Copy Section

• -c, --compress - Outputs compact JSON

Subcommands Copy Section

api list

Returns cached Flutter versions as JSON.

fvm api list [options]

Options:

• -s, --skip-size-calculation - Skips cache size calculation

api releases

Returns available Flutter releases as JSON.

fvm api releases [options]

Options:

• --limit <number> - Limits results
• --filter-channel <channel> - Filters by channel (stable, beta, dev)

api context

Returns FVM environment information as JSON.

fvm api context

api project

Returns project configuration as JSON.

fvm api project [options]

Options:

• -p, --path - Project directory path

Examples Copy Section

# Get cached versions
fvm api list

# Get stable releases (limit 10)
fvm api releases --filter-channel stable --limit 10

# Get project info for specific path
fvm api project --path /projects/myapp

# Get compact JSON output
fvm api context --compress

Command routing Copy Chapter

When using proxy commands (flutter, dart, exec), FVM searches for the SDK in this order:

1. Project configuration
2. Ancestor directory configuration
3. Global FVM setting
4. System PATH

This ensures the correct SDK version is always used.

File: docs/pages/documentation/guides/global-configuration.mdx Copy Chapter

id: global_version title: Configure Global Version Copy Chapter

import { Callout } from "nextra/components";

Overview

You can have the default Flutter version on your machine and still preserve dynamic switching. This allows you to make no changes to how you currently use Flutter, but benefit from faster switching and version caching.

If you are configuring a global version, FVM will check if the global version is set in your environment path. If it is not, it will provide you with the path that needs to be configured.

Link global version Copy Section

To accomplish this, FVM provides you with a helper command to configure a global version.

fvm global {version}

Now you will be able to do the following.

# Set beta channel as global
fvm global beta

# Check version
flutter --version # Will be beta release

# Set stable channel as global
fvm global stable

# Check version
flutter --version # Will be stable release

2. Official Technical Reference & Guides (leoafarias/website) Copy Chapter

[Flutter][]'s website ![Flutter logo][]

Table of contents Copy Chapter

• Issues, bugs, and requests
• Before you build this site
  • 1. Get the prerequisites
  • 2. Clone this repo and its submodules
  • 3. Run installation scripts
• Developing and serving changes
• Creating and/or editing DartPad example code
  • DartPad example code in GitHub gists
  • DartPad example code in this repo - src/_packages/dartpad_picker
• Deploy to a staging site
  • Alternate deployment script
• Deploying to the official site
• Writing for flutter.dev

Issues, bugs, and requests Copy Chapter

We welcome contributions and feedback on our website!
Please file a request in our
issue tracker
and we'll take a look.

NOTE: For simple changes (such as to CSS and text), you probably don't need to
build this site. Often, you can make changes using the GitHub UI.
If you want/need to build, read on.

Before you build this site Copy Chapter

1. Get the prerequisites Copy Section

Install the following tools, if you don't have them already.

• bash, the Bourne shell. These instructions assume you're using bash -- setup might not work if you use another shell.

• nvm, the Node Version Manager.

  NOTE: To make nvm immediately available in your current shell, run source . For example:

  console Copy

  $ source ~/.nvm/nvm.sh

• rvm, the Ruby Version Manager.

  NOTE: To make rvm immediately available in your current shell, run source . For example:

  console Copy

  $ source ~/.rvm/bin/rvm

• Flutter (You get Dart when you get Flutter. Confirm with
  which flutter and which dart.)

• GNU diffutils version 3.6 or later.

  NOTE: diff v3.6+ is required to ensure that in-page code diffs are
  consistently refreshed across macOS and Linux. Issue #3076 was due to
  the default macOS diff being at v2.x. To upgrade diffutils, run:

  console Copy

  $ brew install diffutils

IMPORTANT: Follow the installation instructions for each of the tools
carefully. In particular, configure your shell/environment so
that the tools are available in every terminal/command window you create.

2. Clone this repo _and_ its submodules Copy Section

NOTE: This repo has git submodules, which affects how you clone it.

To clone flutter/website (this repo), follow the instructions given in the
GitHub help on Cloning a repository, then choose one of the following
submodule-cloning techniques:

• Clone this repo and its submodule at the same, use the
  --recurse-submodules option:

  console Copy

  $ git clone --recurse-submodules https://github.com/flutter/website.git

  OR

• If you've already cloned this repo without its submodule, then run
  this command from the repo root:

  console Copy

  $ git submodule update --init --remote

NOTE: At any time during development you can use the git submodule command to
refresh submodules:

console Copy

$ git pull; git submodule update --init --remote

3. Run installation scripts Copy Section

NOTE: It is safe to (re-)run all of the commands and scripts given below even
if you already have the required packages installed.

Open a bash terminal/command window and execute the following commands:

1. After you have cloned this repo, change to the root of this repo:

   console Copy

   $ cd

2. Run the env-set.sh script to initialize environment variables, and to install/use required Node & Ruby version:

   console Copy

   $ source ./tool/env-set.sh

3. Run before-install.sh to install the core set of required tools:

   console Copy

   $ ./tool/before-install.sh

4. Run install.sh to install everything else needed to build this site:

   console Copy

   $ ./tool/install.sh

IMPORTANT:

• Any time you create a new terminal/command window to work on
  this repo, repeat steps 1 and 2 above.

Developing and serving changes Copy Chapter

1. After you clone this repo, create a branch. For example:

   console Copy

   $ git checkout -b

2. Make your changes, then commit them to the branch.

3. Test your changes by serving the site locally.
   To serve locally, run either one of these commands:

   • console Copy

     $ ./tool/serve.sh # or npm run start

   OR

   • console Copy

     $ bundle exec jekyll serve --incremental --watch --livereload --port 4002

     NOTE: Unless you're editing files under site-shared, you can safely
     ignore ERROR: directory is already being watched messages.
     For details, see #1363.

     NOTE: The first time you run either one of these commands,
     Jekyll takes anywhere between 10-20 seconds to generate static
     content inside the _sites directory. If you try to verify the
     site locally, but aren't able to see the content right away,
     wait 20 seconds before stopping the
     server or concluding that something is wrong.

4. Before submitting, validate site links:

   console Copy

   $ ./tool/shared/check-links.sh

TIP: Sometimes Jekyll gets confused and seems to be out-of-sync. (This might
happen, for example, when you pull from master and lots of files have moved.)
To fix Jekyll, stop the serve.sh script, remove the generated site files:
hand, and then restart the serve.sh script:

console Copy

$ npm run clean

OR

console Copy

$ jekyll clean

OR

console Copy

$ rm -Rf ./_site/* ./.jekyll*

Next, restart the serve.sh script:

console Copy

$ npm run start

OR

console Copy

$ ./tool/serve.sh

Creating and/or editing DartPad example code Copy Chapter

Most of the code used to create DartPad examples is hosted on GitHub. However, this repo also contains
some .dart files responsible for DartPad example code.

DartPad example code in GitHub gists Copy Section

A typical DartPad example takes the form of an iframe, for example, within a codelab's markdown file:

This iframe depends on the following GitHub gist url:

https://gist.github.com/d7b09149ffee2f0535bb0c04d96987f5

For detailed instructions on how to use this approach to DartPad examples, see the DartPad embedding guide.

DartPad example code in this repo - `src/_packages/dartpad_picker` Copy Section

Some DartPad example code remains in .dart files in this repo, and must be compiled via src/_packages/dartpad_picker/compile.sh. For an example, consult src/_packages/dartpad_picker/web/dartpad_picker_main.dart.

In order to create or change example code using dartpad_picker, you must regenerate the JavaScript:

$ cd src/_packages/dartpad_picker
  $ ./compile.sh

Deploy to a staging site Copy Chapter

You can deploy your local edits to a personal staging site as follows.

1. Serve your changes locally, as previously instructed.
   Keep the serve.sh script running in its own bash shell.

2. In the Firebase Console,
   create your own Firebase project (e.g. my-foo). You only need
   to do this step once.

3. In a separate bash shell, change to the repo directory and
   initialize Firebase:

   console Copy

   $ npx firebase init

4. Tell Firebase about your project with the
   firebase use command
   You only need to do this step once:

   console Copy

   $ npx firebase use --add
   ? Which project do you want to add? <select the project you created>
   ? What alias do you want to use for this project? (e.g. staging) my-foo

5. Tell Firebase that you want to deploy to staging:

   console Copy

   $ npx firebase use my-foo
   Now using alias staging (my-foo)

6. Tell Firebase to execute deployment of your project:

$ npx firebase deploy

Your personal version of the Flutter website is now deployed to Firebase.
Copy the serving URL from the command output.

Alternate deployment script Copy Section

Alternatively, you can skip the previous steps and just use the deploy script:

$ ./tool/shared/deploy.sh --local my-foo

=== Deploying to '<your project name>'...

i  deploying hosting
i  hosting: preparing _site directory for upload...
✔  hosting: 213 files uploaded successfully
i  starting release process (may take several minutes)...

✔  Deploy complete!

Deploying to the official site Copy Chapter

As of Feb 23, 2021, official site deploys are
performed by GitHub Actions.
In the event that you need to manually deploy,
use the deploy script and the default project:

$ ./tool/shared/deploy.sh --local --robots ok default

Writing for flutter.dev Copy Chapter

The site-shared repo
contains infrastructure shared by most of our Dart and Flutter websites.
Some of this README is in the
doc
directory in the site-shared repo.

For more information on using and writing for this repo,
refer to the following docs:

• Infrastructure
• Markdown
• Examples
• Code excerpts

Also check out the site-shared
wiki:

• Images
• Mobile friendly pages: tips & tricks
• Writing for Dart and Flutter websites