이 글에서 다루는 내용

Flutter 프로젝트를 여러 개 동시에 관리하다 보면 프로젝트마다 요구하는 Flutter 버전이 다를 수 있습니다. 이 글에서는 FVM(Flutter Version Manager)을 사용해 프로젝트별로 Flutter 버전을 독립적으로 관리하는 방법과, Android Studio 및 터미널에서 FVM을 편리하게 사용하는 설정 방법을 다룹니다.

FVM이란?

FVM은 Flutter Version Manager의 약자로, 프로젝트마다 다른 Flutter 버전을 독립적으로 설치하고 관리할 수 있게 해주는 도구입니다. 하나의 시스템에서 여러 버전의 Flutter를 공존시키고, 프로젝트 단위로 사용할 버전을 고정할 수 있습니다.

왜 fvm 접두어를 붙여야 하나요?

flutter pub get, flutter run 등의 명령어를 그냥 실행하면 시스템에 설치된 Flutter(시스템 Flutter)가 실행됩니다. FVM으로 지정한 버전을 사용하려면 명령어 앞에 fvm을 붙여야 합니다.

flutter pub get      # 시스템 Flutter 사용 ❌
fvm flutter pub get  # FVM으로 지정한 버전 사용 ✅

자주 쓰는 명령어 예시입니다.

fvm flutter run
fvm flutter build apk
fvm flutter pub get

fvm flutter build apk 의미

fvm flutter build apk는 FVM으로 관리되는 Flutter 버전으로 Android APK 파일을 빌드하는 명령어입니다. 각 부분의 의미는 다음과 같습니다.

  • fvm — 프로젝트에 지정된 Flutter 버전을 사용
  • flutter build — 배포용 결과물 생성
  • apk — Android Package 형식으로 빌드

자주 사용하는 빌드 옵션입니다.

fvm flutter build apk --release       # 최적화된 릴리즈 APK
fvm flutter build apk --debug         # 디버그 APK
fvm flutter build apk --split-per-abi # CPU 아키텍처별 APK 분리
fvm flutter build appbundle           # Google Play 업로드용 .aab

결과물은 build/app/outputs/flutter-apk/ 경로에 생성됩니다.

프로젝트에 Flutter 버전 고정하기

특정 프로젝트에서만 새로운 Flutter 버전을 사용하고 싶을 때는 아래 명령어로 버전을 고정합니다.

cd {프로젝트 폴더}
fvm use 3.41.6

이 명령어를 실행하면 프로젝트 루트에 .fvm/fvm_config.json 파일이 생성되고 버전이 기록됩니다.

{
  "flutter": "3.41.6"
}

다른 프로젝트는 각자의 .fvm/fvm_config.json에 따라 독립적으로 버전이 유지됩니다.

현재 프로젝트  →  Flutter 3.41.6 ✅
다른 프로젝트  →  Flutter 3.32.6 유지 ✅

Android Studio에서 FVM 버전 사용하기

Android Studio는 기본적으로 시스템 Flutter를 바라보기 때문에 SDK 경로를 변경해야 합니다.

Settings → Languages & Frameworks → Flutter → Flutter SDK path

경로를 아래와 같이 변경합니다.

{프로젝트 경로}/.fvm/flutter_sdk

.fvm/flutter_sdk는 FVM이 자동으로 생성하는 심볼릭 링크로, 실제로는 FVM이 관리하는 버전 폴더를 가리킵니다. Android Studio가 심볼릭 링크를 따라가 실제 경로로 저장하더라도 정상적으로 동작합니다.

.fvm 폴더는 .으로 시작하는 숨김 폴더이므로 파인더 창에서 보이지 않을 수 있습니다. 이때는 아래 단축키로 숨김 폴더를 표시할 수 있습니다.

Mac:     Cmd + Shift + .
Windows: 보기 → 숨긴 항목 표시

또는 Cmd + Shift + G를 눌러 경로를 직접 입력하는 방법이 더 빠릅니다.

VS Code에서 FVM 버전 사용하기

프로젝트 루트의 .vscode/settings.json에 아래 내용을 추가합니다.

{
  "dart.flutterSdkPath": ".fvm/flutter_sdk"
}

이렇게 하면 VS Code의 Run 버튼도 FVM으로 지정한 버전으로 실행됩니다.

터미널에서 fvm 없이 사용하기 — alias 설정

Android Studio 내장 터미널을 포함해 터미널에서는 fvm을 매번 붙여야 합니다. 아래 alias를 등록하면 기존 습관 그대로 사용할 수 있습니다.

echo 'alias flutter="fvm flutter"' >> ~/.zshrc
echo 'alias dart="fvm dart"' >> ~/.zshrc
source ~/.zshrc

이후에는 fvm 없이 그냥 입력해도 FVM 버전으로 실행됩니다.

flutter run
flutter pub get
flutter build apk

각 프로젝트의 .fvm/fvm_config.json을 자동으로 찾아 해당 버전으로 실행하기 때문에 프로젝트 간 버전 충돌이 없습니다. FVM을 사용하는 팀 프로젝트에서는 거의 필수 설정이라고 할 수 있습니다.

전역 버전 설정은 주의가 필요합니다

fvm global {버전}으로 전역 버전을 설정할 수도 있지만, .fvm 설정이 없는 프로젝트는 전역 버전으로 실행됩니다. 프로젝트마다 다른 버전을 사용하는 환경이라면 alias 방식이 더 안전합니다.

설정 방법 총정리

환경 설정 방법
Android Studio SDK path를 .fvm/flutter_sdk로 변경
VS Code .vscode/settings.json에 dart.flutterSdkPath 추가
터미널 ~/.zshrc에 alias 등록