## 1. Project Overview & Quickstart (leoafarias/fvm)
## File: README.md
# fvm
[](https://pub.dev/packages/fvm/changelog)
[](https://pub.dev/packages/fvm/score)
[](https://pub.dev/packages/fvm/score)
[](https://github.com/leoafarias/fvm/graphs/contributors)
[](https://opensource.org/licenses/mit-license.php)
[](https://github.com/Solido/awesome-flutter)
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?
- Need for simultaneous use of multiple Flutter SDKs.
- SDK testing requires constant [channel](https://github.com/flutter/flutter/wiki/Flutter-build-release-channels) 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](https://fvm.app/documentation/getting-started).
## Release Process (For Maintainers)
FVM uses GitHub releases to trigger automated deployments across all platforms:
### Creating a New Release
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](https://github.com/leoafarias/fvm/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`](.github/workflows/release.yml) triggers automatically
- Deploys to: pub.dev, GitHub binaries, Homebrew, Chocolatey, Docker
- Monitor progress in [Actions tab](https://github.com/leoafarias/fvm/actions)
> **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
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](.github/workflows/README.md) for detailed information.
## Contributors
---
Checkout Flutter Sidekick. [Read more about it here.](https://github.com/leoafarias/sidekick)
## Troubleshooting
Please view our [FAQ](https://fvm.app/documentation/getting-started/faq).
## License
This project is licensed under the MIT License; see [LICENSE](LICENSE) file for details.
---
## File: docs/pages/documentation/advanced/custom-version.mdx
---
title: Custom Flutter SDK (Forks)
---
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)
The simplest way is to use the `fork` command:
```bash
# 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](/documentation/guides/basic-commands#fork).
## Alternative Methods
## **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:**
```bash
fvm list
```
Output:
```ansi terminal
Cache directory: /Users/{user}/fvm/versions
Directory Size: 6.47 GB
[37m┌────────────────┬─────────┬────────────────────┬─────────────────┬──────────────┬────────┬───────┐[m
[37m│ [m[1mVersion [m[37m │ [m[1mChannel[m[37m │ [m[1mFlutter Version [m[37m │ [m[1mDart Version [m[37m │ [m[1mRelease Date[m[37m │ [m[1mGlobal[m[37m │ [m[1mLocal[m[37m │[m
[37m├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤[m
[37m│ [mstable [37m │ [mstable [37m │ [m3.24.1 [37m │ [m3.5.1 [37m │ [mAug 21, 2024[37m │ [m [37m │ [m [37m │[m
[37m├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤[m
[37m│ [m3.19.0 [37m │ [mstable [37m │ [m3.19.0 [37m │ [m3.3.0 [37m │ [mFeb 15, 2024[37m │ [m [37m │ [m [37m │[m
[37m└────────────────┴─────────┴────────────────────┴─────────────────┴──────────────┴────────┴───────┘[m
```
**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:
```ansi
Cache directory: /Users/{user}/fvm/versions
Directory Size: 6.47 GB
[37m┌────────────────┬─────────┬────────────────────┬─────────────────┬──────────────┬────────┬───────┐[m
[37m│ [m[1mVersion [m[37m │ [m[1mChannel[m[37m │ [m[1mFlutter Version [m[37m │ [m[1mDart Version [m[37m │ [m[1mRelease Date[m[37m │ [m[1mGlobal[m[37m │ [m[1mLocal[m[37m │[m
[37m├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤[m
[37m│ [mcustom_special[37m │ [m [37m │ [m3.24.0-1.0.pre.575[37m │ [m3.6.0-146.0.dev[37m │ [m [37m │ [m [37m │ [m [37m │[m
[37m├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤[m
[37m│ [mstable [37m │ [mstable [37m │ [m3.24.1 [37m │ [m3.5.1 [37m │ [mAug 21, 2024[37m │ [m [37m │ [m [37m │[m
[37m├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤[m
[37m│ [m3.19.0 [37m │ [mstable [37m │ [m3.19.0 [37m │ [m3.3.0 [37m │ [mFeb 15, 2024[37m │ [m [37m │ [m [37m │[m
[37m└────────────────┴─────────┴────────────────────┴─────────────────┴──────────────┴────────┴───────┘[m
```
**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`:
```bash
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**
```bash
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.
If you already have versions installed, you will have to reinstall them to use the custom repository URL version of them.
**Option 2. Change the environment variable**
You can also change the repository URL by setting the environment variable `FVM_FLUTTER_URL`:
```bash
# 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:
Keep in mind that for each project, the releases and channels need to be different from the ones used in other projects; otherwise, there might be some conflict. A good idea would be to reserve certain versions like `master`, for example.
```json filename=".fvmrc"
{
"flutterUrl": "https://github.com/org/custom-flutter.git"
}
```
---
## File: docs/pages/documentation/advanced/json-api.md
# JSON API
FVM provides JSON API endpoints for integrating with other tools. All commands support the `--compress` option for compact output.
## Commands
### list
Lists installed Flutter SDK versions.
```bash
fvm api list [--compress] [--skip-size-calculation]
```
**Options:**
- `--compress` - Compact JSON output
- `--skip-size-calculation` - Skip cache size calculation
### releases
Shows available Flutter releases.
```bash
fvm api releases [--compress] [--limit ] [--filter-channel ]
```
**Options:**
- `--compress` - Compact JSON output
- `--limit` - Number of releases to return
- `--filter-channel` - Filter by channel (stable, beta, dev)
### context
Returns FVM environment information.
```bash
fvm api context [--compress]
```
### project
Returns project configuration.
```bash
fvm api project [--compress] [--path ]
```
**Options:**
- `--compress` - Compact JSON output
- `--path` - Project directory path
## Integration Example
```bash
# Get current project version
fvm api project --compress | jq -r '.project.pinnedVersion'
# List installed versions
fvm api list --compress | jq -r '.versions[].name'
```
### `list`
Lists the installed Flutter SDK versions available locally.
**Usage:**
```bash
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:**
```json
{
"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`
Provides a list of available Flutter SDK releases.
**Usage:**
```bash
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:**
```json
{
"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`
Returns information about the FVM's current context.
**Usage:**
```bash
fvm api context [options]
```
**Options:**
- `--compress`: Outputs JSON with no whitespace.
**Response Payload:**
```json
{
"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`
Fetches details about the current Flutter project configuration.
**Usage:**
```bash
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:**
```json
{
"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
---
id: release_multiple_channels
title: Release In Multiple Channels
---
# Release In Multiple Channels
Sometimes a Flutter version exists in multiple channels. FVM prioritizes the most stable channel: **stable > beta > dev**.
## Example
Version `3.16.0` exists in both stable and beta channels:
```bash
# Installs from stable channel (default)
fvm use 3.16.0
```
## Force Specific Channel
To install from a specific channel, use `@channel`:
```bash
# Install from beta channel
fvm use 3.16.0@beta
```
---
## File: docs/pages/documentation/getting-started/configuration.mdx
---
id: configuration
title: Configuration
---
import { Callout } from "nextra/components";
import { FileTree } from "nextra/components";
# Configuration
Configure FVM and IDEs for better support for different development environments.
## Project
There are two main parts for a project that has FVM configured: the `.fvmrc` config file and the `.fvm` directory.
### Config File `.fvmrc`
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.
```json
{
"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
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.
Need IDE-specific steps? Follow the [Android Studio and IntelliJ workflow guide](/documentation/guides/workflows#android-studio--intellij) to point the IDE at the project's `.fvm/flutter_sdk` symlink and refresh caches after switching versions.
If `.fvm/flutter_sdk` is missing, run `fvm use ` in the project root to recreate the symlink before reopening the IDE.
Starting with version 3.0 and above, it is recommended to add the `.fvm` directory
to your `.gitignore` file. FVM will automatically add it to .gitignore when
pinning a version to a project if `updateGitIgnore` is set to `true`.
## Environment Variables
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:
- `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:
- `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
---
id: faq
title: FAQ
---
# FAQ
## Upgrade Flutter Channel
As described in our [Principles](https://fvm.app/#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](../guides/running-flutter) section.
---
## flutter and dart commands not found
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 `)
3. Check that the `.fvm` directory exists in your project
---
## How does FVM find the Flutter version to use?
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
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](https://dart.dev/get-dart) for more information.
---
## How to uninstall FVM
**Install script (macOS/Linux):**
```bash
./install.sh --uninstall
```
**Homebrew:**
```bash
brew uninstall fvm
```
**Pub:**
```bash
dart pub global deactivate fvm
```
**Chocolatey (Windows):**
```bash
choco uninstall fvm
```
**Remove cached Flutter versions (optional):**
```bash
fvm destroy
```
---
## Commands run twice on Windows
This happens due to a pub issue [dart-lang:2934](https://github.com/dart-lang/pub/issues/2934). To avoid this issue from happening, make sure your PATH is in the following order. [Please read the following](#environment-variables-order-for-windows-in-path).
---
## Invalid kernel binary or invalid SDK hash when running FVM
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](#environment-variables-order-for-windows-in-path).
2. Run `dart pub global deactivate fvm`.
3. Run `dart pub global activate fvm`.
---
## Command 'pub' not found
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
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:
```bash
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
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](/documentation/troubleshooting/git-safe-directory-windows).
**Quick fix:**
```bash
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
---
id: installation
title: Installation
---
import { Tabs, Callout } from "nextra/components";
# Installation
There are several ways to install FVM. Choose the method that best fits your development environment.
## Recommendation
We recommend installing the Flutter SDK globally using the official installation guide [here](https://docs.flutter.dev/get-started/install). 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](https://github.com/leoafarias/fvm/releases).
## Install Script (Recommended)
Install the latest version:
```bash
curl -fsSL https://fvm.app/install.sh | bash
```
Install a specific version:
```bash
curl -fsSL https://fvm.app/install.sh | bash -s --
```
*Replace `` with your desired FVM version (e.g., `3.2.1`)*
## Homebrew
Install:
```bash
brew install fvm
```
Uninstall:
```bash
brew uninstall fvm
```
## Chocolatey
Install FVM using Chocolatey from the command line or PowerShell:
```bash
choco install fvm
```
Uninstall:
```bash
choco uninstall fvm
```
## Standalone Archive
Native Windows builds are published on the [GitHub Releases](https://github.com/leoafarias/fvm/releases/latest) page.
Download the `windows-x64` or `windows-arm64` zip for your device, extract it, and add the extracted `fvm` directory to your PATH.
## Install Script (Recommended)
Install the latest version:
```bash
curl -fsSL https://fvm.app/install.sh | bash
```
Install a specific version:
```bash
curl -fsSL https://fvm.app/install.sh | bash -s --
```
*Replace `` with your desired FVM version (e.g., `3.2.1`)*
## Alternative Installation
For alternative installation methods, see the [GitHub Releases](https://github.com/leoafarias/fvm/releases/latest) page.
You can also install FVM as a [pub package](https://pub.dev/packages/fvm).
This is not recommended if you plan on using FVM to manage your global Flutter install.
```bash
dart pub global activate fvm
```
Uninstall:
```bash
dart pub global deactivate fvm
```
## Installation Options
### Install Script Features
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 -- ` (replace `` 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
| Platform | Architecture | Support |
|----------|-------------|---------|
| macOS | x64, arm64 | ✅ |
| Linux | x64, arm64, riscv64 | ✅ |
| Windows | x64, arm64 | ✅ (x64 via Chocolatey; x64/arm64 via standalone archive) |
### Requirements
- **macOS/Linux**: `curl` and `tar`
- **Windows**: PowerShell and Chocolatey for Chocolatey installs, or a standalone zip from GitHub Releases
## PATH Configuration
The install script prints instructions to add FVM to your shell PATH. For manual installations, add FVM to your PATH:
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)
For pub installations, add to your shell profile:
```bash
export PATH="$PATH:$HOME/.pub-cache/bin"
```
Add to your PATH environment variable:
```
%USERPROFILE%\AppData\Local\Pub\Cache\bin
```
## Uninstallation
**Install Script:**
```bash
curl -fsSL https://fvm.app/install.sh | bash -s -- --uninstall
```
**Homebrew:**
```bash
brew uninstall fvm
```
**Chocolatey:**
```bash
choco uninstall fvm
```
**Pub:**
```bash
dart pub global deactivate fvm
```
**Remove cached Flutter versions (optional):**
```bash
fvm destroy
```
---
## File: docs/pages/documentation/guides/basic-commands.mdx
---
id: basic_commands
title: Commands Reference
---
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
Sets a Flutter SDK version for the current project. Creates project configuration and ensures environment consistency.
```bash
fvm use [version] [options]
```
### Arguments
- `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
- `-f, --force` - Bypasses Flutter project validation checks
- `-p, --pin` - Pins the latest release of a channel (not for master)
- `--flavor `, `--env ` - Sets version for a specific project flavor
- `-s, --skip-setup` - Skips SDK setup after installation
- `--skip-pub-get` - Skips dependency resolution after switching
### Examples
```bash
# 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
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
Downloads and caches a Flutter SDK version for future use. **Runs setup by default to ensure SDK is ready to use.**
```bash
fvm install [version] [options]
```
### Arguments
- `version` - Flutter SDK version to install (optional)
- If omitted, installs version from project configuration
### Options
- `-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
- `fvm i` - Short form
### Examples
```bash
# 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
Displays all installed Flutter SDK versions.
```bash
fvm list
```
### Aliases
- `fvm ls` - Short form
### Output
Shows all cached SDK versions with their installation paths.
## releases
Shows available Flutter SDK releases for installation.
```bash
fvm releases [options]
```
### Options
- `-c, --channel ` - Filter by channel: stable, beta, dev, all (default: stable)
### Examples
```bash
# Show stable releases
fvm releases
# Show beta channel releases
fvm releases --channel beta
# Show all releases
fvm releases --channel all
```
## remove
Removes Flutter SDK versions from cache.
```bash
fvm remove [version] [options]
```
### Arguments
- `version` - SDK version to remove (prompts if omitted)
### Options
- `-a, --all` - Removes all cached versions
### Examples
```bash
# Remove specific version
fvm remove 3.19.0
# Remove all versions
fvm remove --all
```
## global
Sets a default Flutter SDK version for the system.
```bash
fvm global [version]
```
### Arguments
- `version` - SDK version to set as global
### Options
- `-f, --force` - Bypasses SDK validation
- `-u, --unlink` - Removes global version setting
### Examples
```bash
# Set global version
fvm global 3.19.0
# Remove global version
fvm global --unlink
```
## spawn
Runs Flutter commands with a specific SDK version.
```bash
fvm spawn [args...]
```
### Arguments
- `version` - SDK version to use (required)
- `flutter_command` - Flutter command to execute
- `args` - Additional command arguments
### Examples
```bash
# Build with specific version
fvm spawn 3.19.0 build apk
# Run tests with different version
fvm spawn 3.16.0 test
```
## exec
Executes commands using the project's configured Flutter SDK.
```bash
fvm exec [args...]
```
### Arguments
- `command` - Command to execute
- `args` - Command arguments
### Examples
```bash
# Run melos with project SDK
fvm exec melos bootstrap
# Execute custom script
fvm exec ./scripts/build.sh
```
## flutter
Runs Flutter commands using the project's configured SDK.
```bash
fvm flutter [args...]
```
### Arguments
- `command` - Flutter command to run
- `args` - Command arguments
### Examples
```bash
# Common Flutter commands
fvm flutter doctor
fvm flutter build apk
fvm flutter test
fvm flutter run
```
### Note
Prevents `flutter upgrade` on release versions. Use channels for upgrades.
## dart
Runs Dart commands using the project's configured SDK.
```bash
fvm dart [args...]
```
### Arguments
- `command` - Dart command to run
- `args` - Command arguments
### Examples
```bash
# Common Dart commands
fvm dart pub get
fvm dart analyze
fvm dart format .
fvm dart run build_runner build
```
## destroy
Removes the entire FVM cache and all installed versions.
```bash
fvm destroy [options]
```
### Options
- `-f, --force` - Bypasses confirmation prompt (use with caution)
### Examples
```bash
# Remove cache with confirmation prompt
fvm destroy
# Remove cache without confirmation (dangerous)
fvm destroy --force
```
### Warning
This action is irreversible and removes all cached Flutter SDKs.
## flavor
Executes Flutter commands using a flavor-specific SDK version.
```bash
fvm flavor [args...]
```
### Arguments
- `flavor` - Project flavor name
- `flutter_command` - Flutter command to execute
- `args` - Command arguments
### Examples
```bash
# Build with development flavor
fvm flavor development build apk
# Test with staging flavor
fvm flavor staging test
```
## fork
Manages Flutter fork aliases for custom repositories.
### Subcommands
#### fork add
Adds a fork alias for a custom Flutter repository.
```bash
fvm fork add
```
**Arguments:**
- `alias` - Short name for the fork
- `url` - Git repository URL (must end with .git)
**Example:**
```bash
fvm fork add mycompany https://github.com/mycompany/flutter.git
```
#### fork remove
Removes a fork alias.
```bash
fvm fork remove
```
**Example:**
```bash
fvm fork remove mycompany
```
#### fork list
Shows all configured fork aliases.
```bash
fvm fork list
```
### Using forks
After adding a fork, use it with any version:
```bash
# Install fork version
fvm install mycompany/stable
fvm install mycompany/3.19.0
# Use fork version
fvm use mycompany/stable
```
## config
Manages global FVM settings.
```bash
fvm config [options]
```
### Options
- `--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
```bash
# 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
Shows detailed FVM environment information and diagnostics.
```bash
fvm doctor
```
### Output includes
- Project configuration
- IDE integration status
- Environment details
- Path validation
- FVM version
Useful for troubleshooting configuration issues.
## api
Provides JSON output for integration with other tools.
### Common options
- `-c, --compress` - Outputs compact JSON
### Subcommands
#### api list
Returns cached Flutter versions as JSON.
```bash
fvm api list [options]
```
**Options:**
- `-s, --skip-size-calculation` - Skips cache size calculation
#### api releases
Returns available Flutter releases as JSON.
```bash
fvm api releases [options]
```
**Options:**
- `--limit ` - Limits results
- `--filter-channel ` - Filters by channel (stable, beta, dev)
#### api context
Returns FVM environment information as JSON.
```bash
fvm api context
```
#### api project
Returns project configuration as JSON.
```bash
fvm api project [options]
```
**Options:**
- `-p, --path ` - Project directory path
### Examples
```bash
# 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
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
---
id: global_version
title: Configure Global Version
---
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.
It is recommended that you install FVM as a standalone executable instead of
through pub.dev to avoid dependency conflicts.
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
To accomplish this, FVM provides you with a helper command to configure a global version.
```bash
fvm global {version}
```
Now you will be able to do the following.
```bash title="Example"
# 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
```
After you run the command, FVM will check if the global version is configured
in your environment path. If it is not, it will provide you with the path that
needs to be configured.
## 2. Official Technical Reference & Guides (leoafarias/website)
# [Flutter][]'s website ![Flutter logo][]
[![Build Status][]][Repo on GitHub Actions]
## Table of contents
* [Issues, bugs, and requests](#issues-bugs-and-requests)
* [Before you build this site](#before-you-build-this-site)
- [1. Get the prerequisites](#1-get-the-prerequisites)
- [2. Clone this repo _and_ its submodules](#2-clone-this-repo-and-its-submodules)
- [3. Run installation scripts](#3-run-installation-scripts)
* [Developing and serving changes](#developing-and-serving-changes)
* [Creating and/or editing DartPad example code](#creating-andor-editing-dartpad-example-code)
- [DartPad example code in GitHub gists](#dartpad-example-code-in-github-gists)
- [DartPad example code in this repo - `src/_packages/dartpad_picker`](#dartpad-example-code-in-this-repo---src_packagesdartpad_picker)
* [Deploy to a staging site](#deploy-to-a-staging-site)
- [Alternate deployment script](#alternate-deployment-script)
* [Deploying to the official site](#deploying-to-the-official-site)
* [Writing for flutter.dev](#writing-for-flutterdev)
## Issues, bugs, and requests
We welcome contributions and feedback on our website!
Please file a request in our
[issue tracker](https://github.com/flutter/website/issues/new)
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
### 1. Get the prerequisites
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
> $ source ~/.nvm/nvm.sh
> ```
- **[rvm][]**, the Ruby Version Manager.
> NOTE: To make `rvm` immediately available in your current shell, run `source `. For example:
> ```console
> $ source ~/.rvm/bin/rvm
> ```
- **[Flutter][Flutter install]** (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
> $ brew install diffutils
> ```
> [issue #3076]: https://github.com/flutter/website/issues/3076
> 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
> 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
$ 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
$ git submodule update --init --remote
```
> NOTE: At any time during development you can use the `git submodule` command to
> refresh submodules:
> ```console
> $ git pull; git submodule update --init --remote
> ```
### 3. Run installation scripts
> 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
$ cd
```
1. Run the `env-set.sh` script to initialize environment variables, and to install/use required Node & Ruby version:
```console
$ source ./tool/env-set.sh
```
1. Run `before-install.sh` to install the core set of required tools:
```console
$ ./tool/before-install.sh
```
1. Run `install.sh` to install everything else needed to build this site:
```console
$ ./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
1. After you clone this repo, create a branch. For example:
```console
$ git checkout -b
```
1. Make your changes, then commit them to the branch.
1. Test your changes by serving the site locally.
To serve locally, run _either one_ of these commands:
- ```console
$ ./tool/serve.sh # or npm run start
```
OR
- ```console
$ 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](https://github.com/flutter/website/issues/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.
1. Before submitting, validate site links:
```console
$ ./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
> $ npm run clean
> ```
> OR
> ```console
> $ jekyll clean
> ```
> OR
> ```console
> $ rm -Rf ./_site/* ./.jekyll*
> ```
> Next, restart the `serve.sh` script:
> ```console
> $ npm run start
> ```
> OR
> ```console
> $ ./tool/serve.sh
> ```
## Creating and/or editing DartPad example code
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
A typical DartPad example takes the form of an `iframe`, for example, within a codelab's markdown file:
```markdown
```
This `iframe` depends on the following GitHub gist url:
```none
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`
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:
```sh
$ cd src/_packages/dartpad_picker
$ ./compile.sh
```
## Deploy to a staging site
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.
1. In the [Firebase Console](https://console.firebase.google.com),
create your own Firebase project (e.g. `my-foo`). You only need
to do this step once.
1. In a separate `bash` shell, change to the repo directory and
initialize Firebase:
```console
$ npx firebase init
```
1. Tell Firebase about your project with the
[`firebase use` command](https://firebase.googleblog.com/2016/07/deploy-to-multiple-environments-with.html)
You only need to do this step once:
```console
$ npx firebase use --add
? Which project do you want to add?