ZebEd - Tech Education Platform

FVM (Flutter Version Management) is a powerful version management tool that allows you to install, cache, and switch between multiple Flutter SDK versions seamlessly across different projects.

FVM (Flutter Version Management) Complete Guide

FVM is an essential tool for Flutter developers that enables you to manage multiple Flutter SDK versions on the same machine. This comprehensive guide covers everything from installation to advanced workflows for efficient Flutter development.

Installation & Setup

Get FVM up and running on your macOS system with these simple steps.

# Install FVM using Dart's package manager
dart pub global activate fvm

# Add FVM to your PATH (add to ~/.zshrc)
echo 'export PATH="$PATH":"$HOME/.pub-cache/bin"' >> ~/.zshrc

# Reload your shell configuration
source ~/.zshrc

# Verify installation
fvm --version

Installing Flutter Versions

Learn how to install different Flutter SDK versions using FVM.

# Install specific Flutter versions
fvm install 3.27.3
fvm install 3.22.2
fvm install 3.16.9

# Install channel versions
fvm install stable
fvm install beta
fvm install dev
fvm install master

# List all installed versions
fvm list

# List all available releases
fvm releases

Project Version Management

Manage Flutter versions on a per-project basis for maximum flexibility.

# Navigate to your project
cd /path/to/your/project

# Set Flutter version for this project
fvm use 3.27.3

# Use channel versions in projects
fvm use stable
fvm use beta

# Check current project version
fvm flutter --version

# Show project FVM status
fvm status

Global Version Management

Set up default Flutter versions for your system.

# Set global default version
fvm global 3.27.3

# Set global to stable channel
fvm global stable

# Check current global version
fvm global

# List versions with global indicator
fvm list

Using Flutter Commands with FVM

Always prefix Flutter commands with FVM in your projects to ensure you're using the correct version.

# Standard Flutter commands with FVM
fvm flutter pub get
fvm flutter run
fvm flutter build apk
fvm flutter build ios
fvm flutter test
fvm flutter analyze
fvm flutter doctor
fvm flutter clean
fvm flutter pub upgrade

IDE Configuration

Configure your development environment to work seamlessly with FVM.

VS Code Setup:

Create **.vscode/settings.json** in your project:

{
  "dart.flutterSdkPath": ".fvm/flutter_sdk",
  "search.exclude": {
    "**/.fvm": true
  },
  "files.watcherExclude": {
    "**/.fvm": true
  }
}

Android Studio/IntelliJ Setup:

Install FVM plugin from JetBrains marketplace
OR manually set Flutter SDK path to: [project]/.fvm/flutter_sdk

Version Management & Cleanup

Keep your FVM installation organized and clean.

# Remove specific versions
fvm remove 3.27.1
fvm remove stable

# Remove all versions (use with caution)
fvm remove --all

# Clean FVM cache
fvm cache clean

# Repair FVM cache
fvm cache repair

Useful Aliases & Shortcuts

Create terminal aliases for faster development workflow.

# Add to **~/.zshrc** for permanent aliases
alias ff='fvm flutter'
alias ffpg='fvm flutter pub get'
alias ffr='fvm flutter run'
alias ffb='fvm flutter build'
alias ffd='fvm flutter doctor'
alias fft='fvm flutter test'
alias ffa='fvm flutter analyze'

Project Structure with FVM

Understand how FVM organizes your projects.

Project Directory Structure:

your-project/
├── .fvm/
│   └── flutter_sdk -> /Users/username/fvm/versions/3.27.3
├── lib/
├── test/
├── .vscode/
│   └── settings.json
├── pubspec.yaml
└── .gitignore

Git Integration

Configure Git to work properly with FVM.

# Add to .gitignore
.fvm/

Optional: Commit fvm_config.json to share version with team:

{
  "flutterSdkVersion": "3.27.3",
  "flavors": {}
}

Common Workflows

Practical scenarios for using FVM in daily development.

New Project Setup:

# Create new project
fvm flutter create my_app
cd my_app

# Set Flutter version
fvm use 3.27.3

# Configure IDE
# Start development
fvm flutter run

Clone Existing Project:

# Clone project
git clone project-url
cd project

# Install required Flutter version
fvm install

# Verify setup
fvm flutter --version
fvm flutter doctor

Switch Between Projects:

# Project A (uses 3.27.3)
cd project-a
fvm use 3.27.3
fvm flutter run

# Project B (uses stable)  
cd project-b
fvm use stable
fvm flutter run

Troubleshooting Common Issues

Solve common FVM problems quickly.

Command not found: fvm

source ~/.zshrc
# OR
chmod +x ~/.pub-cache/bin/fvm

Need setup in fvm list

fvm remove version_name
fvm install version_name

IDE not detecting FVM

Restart IDE
Check SDK path in IDE settings
Verify .fvm/flutter_sdk symlink exists

Permission Issues

sudo chown -R $(whoami) /Users/username/fvm

Best Practices

Follow these guidelines for optimal FVM usage.

Development Practices:

Always use fvm flutter instead of just flutter in projects
Commit fvm_config.json to share version with team
Add .fvm to .gitignore to avoid committing SDK
Use stable channels for production projects
Regularly update FVM and Flutter versions
Use consistent versions across team projects

Quick Reference Commands:

fvm use [version]          # Switch project version
fvm flutter run           # Run project
fvm flutter pub get       # Get dependencies
fvm list                  # Check installed versions
fvm install stable        # Update to latest stable
fvm remove old_version    # Clean up old versions

By mastering FVM, you gain complete control over your Flutter development environment, enabling seamless switching between projects with different Flutter requirements while maintaining a stable global setup for general use.

FVM - Flutter Version Management