Common Workflows

Quick guides for typical FVM tasks. Each workflow shows the essential commands to accomplish specific goals.

Setting up a new project

Configure a Flutter project to use a specific SDK version.

# Navigate to project
cd myproject
 
# Set Flutter version
fvm use 3.19.0
 
# Or use latest stable
fvm use stable --pin

Result: Creates .fvm directory and .fvmrc configuration file.

Switching between versions

Change SDK versions for different projects or testing.

# Check current version
fvm list
 
# Switch to different version
fvm use 3.16.0
 
# Force switch without validation
fvm use 3.16.0 --force

Working with multiple flavors

Manage different SDK versions for development, staging, and production.

# Set development version
fvm use 3.19.0 --flavor development
 
# Set production version
fvm use 3.16.0 --flavor production
 
# Use flavor-specific version
fvm flavor development build apk

Testing with different versions

Run tests across multiple Flutter SDK versions.

# Test with current project version
fvm flutter test
 
# Test with specific version
fvm spawn 3.19.0 test
 
# Test with another version
fvm spawn 3.16.0 test

CI/CD integration

Set up FVM in continuous integration pipelines.

# Install FVM
dart pub global activate fvm
 
# Install project SDK version
fvm install
 
# Run Flutter commands
fvm flutter build apk --release

Managing custom forks

Use company or personal Flutter forks.

# Add fork
fvm fork add company https://github.com/company/flutter.git
 
# Install from fork
fvm install company/stable
 
# Use fork version
fvm use company/3.19.0

Global version setup

Configure a system-wide default Flutter version.

# Set global version
fvm global 3.19.0
 
# Add to PATH (one-time setup)
export PATH="$PATH:$HOME/fvm/default/bin"
 
# Use global version
flutter doctor

Cleaning up old versions

Remove unused SDK versions to free disk space.

# List installed versions
fvm list
 
# Remove specific version
fvm remove 3.16.0
 
# Remove all versions
fvm remove --all

Monorepo setup

Configure FVM for projects with multiple Flutter apps.

# Root configuration
cd monorepo
fvm use 3.19.0
 
# App-specific versions
cd apps/mobile
fvm use 3.16.0
 
# Package uses root version
cd packages/shared
# Inherits from root

Offline installation

Install Flutter SDK from local cache or network share.

# Configure custom cache path
fvm config --cache-path /shared/flutter-cache
 
# Disable git cache for offline use
fvm config --no-use-git-cache
 
# Install from local cache
fvm install 3.19.0

Troubleshooting

Common solutions for FVM issues.

# Check environment
fvm doctor
 
# Verify project setup
cd myproject
fvm doctor
 
# Force reinstall
fvm remove 3.19.0
fvm install 3.19.0
 
# Reset global config
fvm global --unlink

IDE configuration

VS Code

FVM automatically configures VS Code settings. To manually configure:

Run fvm use <version> in project
Restart VS Code or reload window
Verify SDK path in settings

Android Studio / IntelliJ

FVM keeps a project-scoped symlink at .fvm/flutter_sdk. Running fvm use <version> updates this symlink to point to the selected Flutter SDK version.

Known limitation: Android Studio and IntelliJ resolve symlinks to their absolute target path when saving settings (flutter-intellij#6616 (opens in a new tab)). This means the IDE stores the resolved path (e.g., ~/.fvm/versions/3.19.0) rather than the symlink itself. After running fvm use to switch versions, you may need to re-select the SDK path in settings for the IDE to pick up the new version.

Point the IDE at FVM

Open File → Settings (Windows/Linux) or Android Studio → Preferences (macOS).
Navigate to Languages & Frameworks → Flutter.
Set Flutter SDK path to the absolute path of .fvm/flutter_sdk in your project (e.g., /path/to/project/.fvm/flutter_sdk).
Tip: Paste the path directly into the text field instead of using the file browser—this may help preserve the symlink path in some IDE versions.
Click Apply. Restart the IDE if prompted.

After switching Flutter versions

Run fvm use <version> in the project so .fvm/flutter_sdk points at the new cached SDK.
Re-open Settings → Languages & Frameworks → Flutter and re-select the .fvm/flutter_sdk path so the IDE resolves to the new target.
For Android projects: File → Sync Project with Gradle Files to refresh Gradle metadata. If this option isn't visible, press Ctrl+Shift+A (or Cmd+Shift+A on macOS) and search for "Sync Project with Gradle Files".
If Dart Analysis shows stale errors, open View → Tool Windows → Dart Analysis and click the restart icon in the toolbar.
Run fvm doctor to verify the IDE configuration is correct.

Troubleshooting stale paths

Use File → Invalidate Caches / Restart… to clear cached SDK paths.
Confirm the symlink exists with ls -l .fvm/flutter_sdk. If missing, run fvm use to recreate it.

Multi-module or monorepo setups

Each module should run fvm use within its directory so .fvm/flutter_sdk resolves locally.
Android Studio allows multiple Flutter SDK entries—ensure every module references its own .fvm/flutter_sdk rather than a shared global install.
When switching versions in one module, repeat the Gradle/Flutter sync steps within that module’s window.

Best practices

Version selection

Use specific versions for production apps
Pin channels for active development
Document version requirements in README

Team collaboration

# Add to .gitignore
.fvm/flutter_sdk
 
# Commit these files
.fvmrc
.fvm/fvm_config.json

Performance tips

Enable git cache for faster installs
Use fvm install --no-setup when you only need to cache SDKs (run --setup later via fvm use)
Run fvm install in CI before build steps

Quick Reference Commands Reference