이 글에서 다루는 내용

이 글에서는 macOS 환경에서 Flutter 버전 관리 도구인 FVM을 설치하는 두 가지 방법을 정리한다. 먼저 Homebrew를 이용한 설치 과정을 살펴보고, 이 방식에서 만날 수 있는 Xcode 의존성과 소스 컴파일 문제를 짚어본다. 이어서 공식 install.sh 스크립트를 이용한 설치 방법과 PATH 등록까지의 전체 흐름을 다룬다. 마지막으로 어떤 상황에서 어느 방법을 선택하는 것이 좋은지 비교하고, 글에 등장하는 핵심 용어들을 따로 정리한다.

방법 1. Homebrew로 설치하기

FVM은 Homebrew 공식 저장소(homebrew-core)가 아니라 개발자(leoafarias)의 개인 저장소에 등록되어 있다. 그래서 설치하려면 두 단계가 필요하다.

brew tap leoafarias/fvm
brew install fvm

첫 번째 brew tap은 외부 저장소를 Homebrew에 등록하는 명령이고, 두 번째 brew install이 실제 설치를 수행한다. 비유하자면 tap은 "앱스토어에 새 마켓을 추가"하는 것이고, install은 "그 마켓에서 앱을 다운로드"하는 것이다.

한 줄로 줄이고 싶다면 전체 경로를 명시해 tap을 자동 처리할 수도 있다.

brew install leoafarias/fvm/fvm

Homebrew 방식에서 만나는 문제들

이 방식은 깔끔해 보이지만 실제로는 몇 가지 걸림돌이 있다.

첫째, 신뢰 경고가 뜬다. 최근 Homebrew는 서드파티 tap에 대해 명시적 신뢰 등록을 요구하는 정책으로 바뀌고 있다. leoafarias/fvm tap이 신뢰되지 않았다는 경고가 나오면 다음처럼 신뢰를 등록한다.

brew trust leoafarias/fvm

둘째, Xcode가 필요하다. FVM은 Dart로 만들어졌고, Homebrew는 이를 소스에서 컴파일한다. 이 과정에서 dartaotruntime을 빌드하는데, Command Line Tools만으로는 부족하고 Xcode 정식 앱이 요구된다.

dartaotruntime: A full installation of Xcode.app is required to compile this software.
Error: fvm: An unsatisfied requirement failed this build.

셋째, 의존성까지 소스 빌드한다. FVM은 서드파티 tap이라 미리 빌드된 바이너리(bottle)가 없다. 그래서 CMake 같은 의존 패키지까지 전부 소스에서 컴파일하게 되며, 머신에 따라 make 단계에서만 20~40분 이상이 걸리기도 한다.

==> ./bootstrap --prefix=/usr/local/Cellar/cmake/...
==> make

정리하면, Homebrew 방식은 FVM 하나를 설치하기 위해 Xcode 컴파일과 긴 빌드 시간을 감수해야 하는 비효율이 있다.

방법 2. curl 스크립트로 설치하기 (추천)

FVM 공식 설치 스크립트는 미리 빌드된 바이너리를 바로 내려받기 때문에 Xcode 컴파일도, 긴 소스 빌드도 필요 없다. 수십 분 걸리던 작업이 수십 초로 끝난다.

curl -fsSL https://fvm.app/install.sh | bash

설치가 끝나면 다음과 같은 안내가 나온다.

✓ Installation complete!

To use FVM, add it to your PATH:
  export PATH="/Users/yty/fvm/bin:$PATH"

PATH 등록하기

curl | bash 방식은 바이너리를 ~/fvm/bin에 풀어놓기만 하고 셸 설정 파일은 건드리지 않는다. 사용자 환경을 임의로 수정하지 않으려는 동작이다. 따라서 PATH 등록은 직접 해줘야 한다. 등록을 안 하면 fvm 명령을 입력해도 zsh: command not found: fvm이 뜬다.

zsh 기준으로 설정 파일에 추가한다.

echo 'export PATH="/Users/yty/fvm/bin:$PATH"' >> ~/.zshrc

그다음 현재 셸에 즉시 반영한다.

source ~/.zshrc

마지막으로 설치를 확인한다.

fvm --version
# 4.1.0

버전 번호가 출력되면 설치와 PATH 등록이 모두 정상이다.

설치 후 기본 사용법

FVM이 준비되면 Flutter 버전을 관리할 수 있다.

fvm releases          # 설치 가능한 Flutter 버전 목록
fvm install stable    # 안정 버전 설치

그다음 프로젝트 폴더 안에서 버전을 지정한다.

cd ~/your_flutter_project
fvm use 3.27.0

이러면 프로젝트 루트에 .fvm/ 폴더와 .fvmrc 파일이 생기고, 해당 프로젝트가 지정한 버전으로 고정된다. 이 설정을 커밋해두면 팀원 모두 같은 Flutter 버전을 사용하게 되어 환경 차이로 인한 문제가 줄어든다.

FVM으로 관리하는 프로젝트에서는 flutter 대신 fvm flutter를 앞에 붙여 실행한다.

fvm flutter run
fvm flutter pub get

IDE 연동 설정이 필요하면 fvm doctor로 무엇을 설정해야 하는지 확인할 수 있다.

두 방법 비교

항목 curl 스크립트 Homebrew
설치 속도 빠름 (사전 빌드 바이너리) 느림 (소스 컴파일)
Xcode 필요 불필요 필요
업데이트 fvm update brew upgrade fvm
제거 install.sh --uninstall brew uninstall fvm
의존성 관리 FVM 자체 처리 Homebrew 통합 관리

FVM은 서드파티 tap이라 bottle이 제공되지 않으므로, Homebrew의 "통합 관리"라는 장점이 잘 살지 않는다. 매번 컴파일 비용을 치러야 하기 때문이다. 따라서 대부분의 경우 curl 스크립트 방식이 더 빠르고 간편하다. 모든 CLI 도구를 Homebrew로 일원화하는 워크플로를 강하게 선호하는 경우가 아니라면 curl 스크립트를 권한다.

참고로 iOS 빌드용 Xcode는 FVM 설치 경로와는 무관한 별개의 작업이다. Android나 웹 타겟만 다룬다면 당장 없어도 되지만, iOS 실기기나 시뮬레이터 빌드를 하려면 결국 Xcode가 필요하다. macOS Ventura(13.x)에서는 Xcode 15.2까지 설치할 수 있다.