Flutter 프로젝트별 SDK 버전 관리 — FVM 완벽 가이드 (Windows / macOS)
Flutter 프로젝트를 여러 개 관리하다 보면 프로젝트마다 요구하는 SDK 버전이 다른 상황이 생긴다. 이럴 때 매번 SDK를 수동으로 교체하는 건 비효율적이고 실수도 잦다. FVM(Flutter Version Management)을 사용하면 프로젝트별로 Flutter SDK 버전을 깔끔하게 분리하고, 기존 flutter 명령어를 그대로 사용하면서도 자동으로 버전이 전환되도록 설정할 수 있다.
이 글에서는 Windows와 macOS 각각에서 FVM을 설치하고, 기존 Flutter SDK를 FVM 기반으로 전환하는 과정까지 다룬다.
FVM이란?
FVM은 Flutter SDK 버전을 프로젝트 단위로 관리해주는 CLI 도구다. 핵심 기능은 다음과 같다.
- 프로젝트별로 서로 다른 Flutter SDK 버전을 지정할 수 있다.
- 글로벌 기본 버전을 설정하면 기존
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 명령 실행
fvm flutter run
fvm flutter build apk
fvm flutter pub get
기존 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의 글로벌 버전이 사용된다. 프로젝트 디렉토리에 .fvmrc가 있으면 해당 프로젝트 버전이 자동으로 적용된다.
# 프로젝트 밖 → 글로벌 버전 사용
flutter --version
# 프로젝트 안 → .fvmrc에 지정된 버전 사용
cd my_project
flutter --version
기존 Flutter SDK 폴더는 전환이 안정적으로 동작하는 것을 확인한 후 삭제해도 된다.
IDE 설정
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 절대 경로로 지정한다.
예시:
- Windows:
C:\Users\사용자명\projects\my_project\.fvm\flutter_sdk - macOS:
/Users/사용자명/projects/my_project/.fvm/flutter_sdk
.gitignore 설정
FVM은 프로젝트에 .fvm/ 디렉토리를 생성하는데, 이 안의 flutter_sdk는 심볼릭 링크이므로 버전 관리에서 제외해야 한다. .gitignore에 아래를 추가한다.
.fvm/flutter_sdk
.fvmrc 파일은 팀원과 Flutter 버전을 공유하기 위해 커밋하는 것이 좋다.
자주 쓰는 명령어 정리
| 명령어 | 설명 |
|---|---|
fvm install <버전> | 특정 Flutter 버전 설치 |
fvm use <버전> | 현재 프로젝트에 버전 지정 |
fvm global <버전> | 글로벌 기본 버전 설정 |
fvm list | 설치된 버전 목록 확인 |
fvm releases | 설치 가능한 릴리즈 목록 |
fvm remove <버전> | 특정 버전 삭제 |
fvm flutter <명령> | FVM 경유 Flutter 명령 실행 |
fvm doctor | FVM 환경 진단 |
정리
FVM을 도입하면 프로젝트마다 Flutter SDK 버전을 독립적으로 관리할 수 있고, fvm global + PATH 설정을 통해 기존 flutter 명령어를 그대로 사용하면서도 프로젝트별 자동 전환이 가능하다. 특히 여러 프로젝트를 동시에 유지보수하거나 팀 단위로 SDK 버전을 통일해야 하는 상황에서 큰 도움이 된다. 기존 Flutter SDK를 지울 필요 없이 점진적으로 전환할 수 있으니, 부담 없이 시작해보자.