Flutter 프로젝트별 SDK 버전 관리 — FVM 설정하기 (Windows / macOS)
Flutter 프로젝트를 여러 개 관리하다 보면 프로젝트마다 요구하는 SDK 버전이 다른 상황이 생겨요. 이럴 때 매번 SDK를 수동으로 바꾸는 건 번거롭고 실수도 잦아요. FVM(Flutter Version Management)을 쓰면 프로젝트별로 Flutter SDK 버전을 나눠서 관리할 수 있어요.
이 글에서는 Windows와 macOS에서 FVM을 설치하고, 기존 Flutter SDK를 FVM 기반으로 전환하는 과정까지 다뤄요.
FVM이란?
FVM은 Flutter SDK 버전을 프로젝트 단위로 관리해 주는 CLI 도구예요. 핵심 기능은 이래요.
- 프로젝트별로 서로 다른 Flutter SDK 버전을 지정할 수 있어요.
- 글로벌 기본 버전을 설정하고 PATH에 연결하면, 기존
flutter명령어로 그 버전을 쓸 수 있어요. - 프로젝트 안에서
fvm flutter로 실행하면 그 프로젝트에 지정된 버전이 쓰여요.
설치
Windows
Dart가 이미 설치되어 있다면 (Flutter SDK에 포함) 아래 명령으로 바로 설치할 수 있어요.
dart pub global activate fvm
설치 후 fvm 명령이 인식되지 않는다면 %LOCALAPPDATA%\Pub\Cache\bin이 시스템 PATH에 들어 있는지 확인해요. 보통 Flutter SDK를 설치할 때 자동으로 잡히지만, 직접 추가해야 할 수도 있어요.
macOS
Dart를 통한 설치는 같아요.
dart pub global activate fvm
Homebrew를 쓴다면 아래 방식도 돼요.
brew tap leoafarias/fvm
brew install fvm
macOS에서 fvm 명령이 인식되지 않는 경우 $HOME/.pub-cache/bin이 PATH에 있는지 확인해요. .zshrc 또는 .bashrc에 다음을 추가하면 돼요.
export PATH="$HOME/.pub-cache/bin:$PATH"
기본 사용법
Flutter 버전 설치
fvm install 3.24.0
stable 채널의 최신 버전을 설치하려면 이렇게 입력해요.
fvm install stable
설치된 버전 목록 확인
fvm list
릴리즈 가능한 버전 확인
fvm releases
프로젝트에 버전 지정
프로젝트 루트 디렉토리에서 아래 명령을 실행해요.
cd my_project
fvm use 3.24.0
이 명령을 실행하면 프로젝트 루트에 .fvmrc 파일이 생성되고, .fvm/ 디렉토리 안에 해당 버전 SDK로의 심볼릭 링크(.fvm/flutter_sdk)가 만들어져요.
FVM 경유 Flutter 명령 실행
fvm flutter run
fvm flutter build apk
fvm flutter pub get
fvm flutter는 프로젝트의 .fvmrc → 상위 디렉토리의 .fvmrc → 글로벌 버전(fvm global) → 시스템 PATH 순서로 SDK를 찾아요. 프로젝트별 버전을 쓰려면 이 명령으로 실행해야 해요. 매번 치기 번거로우면 alias f="fvm flutter"처럼 alias를 두면 편해요.
기존 Flutter SDK를 FVM으로 전환하기
FVM을 설치했다고 해서 기존 Flutter SDK를 당장 지울 필요는 없어요. FVM은 자체 디렉토리에 SDK를 따로 관리해서 기존 SDK와 충돌하지 않아요. 다만 터미널에서 flutter를 실행하면 여전히 기존 SDK가 잡혀요. 이걸 FVM의 글로벌 버전으로 바꾸려면 아래 과정을 따라요.
1단계: FVM 글로벌 버전 설정
fvm global 3.24.0
이 명령은 FVM이 관리하는 기본(default) Flutter 버전을 지정해요.
2단계: PATH 변경
Windows
시스템 환경 변수 편집을 열어요. (Win + S → "환경 변수" 검색)- 시스템 변수 또는 사용자 변수의
Path에서 기존 Flutter SDK 경로를 찾아요. 보통C:\flutter\bin또는C:\src\flutter\bin같은 형태예요. - 해당 경로를 제거해요.
- 대신 아래 경로를 추가해요.
%LOCALAPPDATA%\fvm\default\bin
- 터미널을 새로 열고 확인해요.
flutter --version
where flutter
where flutter의 결과가 %LOCALAPPDATA%\fvm\default\bin\flutter를 가리키면 정상이에요.
macOS
.zshrc또는.bashrc를 열어요.
vi ~/.zshrc
- 기존 Flutter SDK 경로를 지우고 FVM 경로로 바꿔요.
# 기존 (제거)
# export PATH="$HOME/flutter/bin:$PATH"
# FVM 기반 (추가)
export PATH="$HOME/fvm/default/bin:$PATH"
- 변경 사항을 적용하고 확인해요.
source ~/.zshrc
flutter --version
which flutter
which flutter의 결과가 FVM default 경로를 가리키면 정상이에요.
3단계: 확인
이제 어느 디렉토리에서든 flutter를 실행하면 FVM의 글로벌 버전이 쓰여요. 이 flutter는 프로젝트 안에서도 글로벌 버전이에요. 프로젝트의 .fvmrc 버전을 쓰려면 fvm flutter로 실행해요.
# 어디서든 → 글로벌 버전
flutter --version
# 프로젝트 안 → .fvmrc에 지정된 버전
cd my_project
fvm flutter --version
그냥 flutter만 쳐도 프로젝트 버전이 쓰이게 하려면, flutter가 내부에서 fvm flutter를 부르도록 감싸는 스크립트를 따로 만들어야 해요. 방법은 FVM 문서의 Running Flutter에 있어요.
기존 Flutter SDK 폴더는 전환이 잘 동작하는 걸 확인한 뒤 지워도 돼요.
IDE 설정
VS Code
FVM은 기본 설정으로 fvm use를 실행할 때 VS Code 설정을 자동으로 맞춰 줘요. 직접 설정하려면 프로젝트 루트의 .vscode/settings.json을 만들거나 고쳐요.
{
"dart.flutterSdkPath": ".fvm/flutter_sdk"
}
이렇게 설정하면 VS Code의 Dart/Flutter 확장이 프로젝트별 FVM SDK를 인식해요.
Android Studio / IntelliJ
Settings → Languages & Frameworks → Flutter에서 Flutter SDK path를 프로젝트의 .fvm/flutter_sdk 절대 경로로 지정해요. FVM은 Android Studio 설정은 자동으로 바꾸지 않아요.
예시:
- Windows:
C:\Users\사용자명\projects\my_project\.fvm\flutter_sdk - macOS:
/Users/사용자명/projects/my_project/.fvm/flutter_sdk
.gitignore 설정
FVM은 프로젝트에 .fvm/ 디렉토리를 만들어요. 이 안에는 심볼릭 링크 같은 로컬 파일이 들어 있어서 버전 관리에서 빼야 해요. FVM 문서는 .fvm/ 전체를 .gitignore에 넣으라고 안내하고, 기본 설정에서는 FVM이 .gitignore를 자동으로 고쳐 줘요.
.fvm/
.fvmrc 파일은 팀원과 Flutter 버전을 공유하기 위해 커밋하는 게 좋아요.
자주 쓰는 명령어 정리
| 명령어 | 설명 |
|---|---|
fvm install <버전> | 특정 Flutter 버전 설치 |
fvm use <버전> | 현재 프로젝트에 버전 지정 |
fvm global <버전> | 글로벌 기본 버전 설정 |
fvm list | 설치된 버전 목록 확인 |
fvm releases | 설치 가능한 릴리즈 목록 |
fvm remove <버전> | 특정 버전 삭제 |
fvm flutter <명령> | FVM 경유 Flutter 명령 실행 |
fvm doctor | FVM 환경 진단 |
정리
- 프로젝트마다
fvm use <버전>으로 Flutter SDK 버전을 지정하고,fvm flutter로 실행하면 그 버전이 쓰여요. fvm global+ PATH 설정으로 기존flutter명령어가 FVM의 글로벌 버전을 가리키게 할 수 있어요.- 기존 Flutter SDK를 바로 지우지 않고 단계적으로 전환할 수 있어요.
