Flutter를 처음 설치하고 설레는 마음으로 명령어를 입력했는데, “flutter: 명령어를 찾을 수 없습니다”라는 메시지가 뜬다면 얼마나 당황스러울까요? 마치 멋진 스포츠카를 뽑았는데, 시동이 걸리지 않는 상황과 비슷할 겁니다. 이 문제는 Flutter 개발 환경을 설정하는 과정에서 흔히 발생하는 문제 중 하나입니다. 하지만 너무 걱정하지 마세요! 이 글에서는 Flutter 설치 후 PATH 설정이 제대로 되지 않아 명령어를 인식하지 못하는 이유를 알아보고, 해결 방법을 단계별로 자세히 설명해 드리겠습니다.
저 또한 처음 Flutter를 접했을 때 이 문제 때문에 꽤나 애를 먹었던 기억이 납니다. 공식 문서대로 따라 했는데도 잘 안 되니 답답했죠. 하지만 여러 시행착오를 거치면서 PATH 설정의 중요성을 깨닫고, 다양한 해결 방법을 익힐 수 있었습니다. 이 글에서는 제가 겪었던 경험과 함께, 여러분이 쉽고 빠르게 문제를 해결할 수 있도록 꼼꼼하게 안내해 드릴 테니, 차근차근 따라오시면 분명히 성공적으로 Flutter 개발 환경을 구축할 수 있을 겁니다.
PATH 환경 변수 이해하기
PATH 환경 변수는 운영체제가 실행 파일을 검색하는 경로들을 담고 있는 목록입니다. 우리가 터미널이나 명령 프롬프트에서 특정 명령어를 입력하면, 운영체제는 PATH에 등록된 경로들을 순서대로 검색하여 해당 실행 파일을 찾습니다. 만약 Flutter SDK의 경로가 PATH에 등록되어 있지 않다면, 운영체제는 ‘flutter’라는 명령어를 찾을 수 없게 되고, “flutter: 명령어를 찾을 수 없습니다”와 같은 오류 메시지를 표시하게 되는 것입니다.
Flutter SDK 경로 확인하기
가장 먼저 확인해야 할 것은 Flutter SDK가 실제로 어디에 설치되어 있는지 확인하는 것입니다. 일반적으로 Flutter SDK는 사용자의 홈 디렉토리나 특정 개발 도구 폴더에 설치됩니다. 설치 과정에서 특별히 경로를 변경하지 않았다면, 다음과 같은 경로에 있을 가능성이 높습니다.
- Windows:
C:\src\flutter또는C:\flutter - macOS:
~/flutterdev/flutter또는~/development/flutter - Linux:
~/flutter또는/opt/flutter
터미널이나 파일 탐색기를 사용하여 Flutter SDK가 설치된 경로를 정확하게 확인해 주세요. 이 경로는 나중에 PATH 환경 변수를 설정할 때 필요합니다. Flutter SDK 폴더 안에는 ‘bin’이라는 하위 폴더가 있는데, 이 ‘bin’ 폴더의 경로를 PATH에 추가해야 합니다. 예를 들어, Flutter SDK가 C:\src\flutter에 설치되었다면, PATH에 추가해야 할 경로는 C:\src\flutter\bin이 됩니다.
운영체제별 PATH 설정 방법
Flutter SDK의 경로를 확인했다면, 이제 운영체제에 따라 PATH 환경 변수를 설정해야 합니다. 각 운영체제별로 설정 방법이 조금씩 다르니, 자신의 운영체제에 맞는 방법을 따라해 주세요.
- Windows:
- “시스템 환경 변수 편집”을 검색하여 시스템 속성 창을 엽니다.
- “환경 변수” 버튼을 클릭합니다.
- “시스템 변수” 목록에서 “Path” 변수를 찾아 선택하고 “편집” 버튼을 클릭합니다.
- “새로 만들기” 버튼을 클릭하고, Flutter SDK의 ‘bin’ 폴더 경로 (예:
C:\src\flutter\bin)를 입력합니다. - “확인” 버튼을 클릭하여 모든 창을 닫습니다.
- macOS:
- 터미널을 엽니다.
nano ~/.bash_profile또는nano ~/.zshrc명령어를 입력하여 텍스트 편집기를 엽니다. (사용하는 쉘에 따라 파일 이름이 다를 수 있습니다.)- 파일의 맨 아래에
export PATH="$PATH:/Users/[사용자 이름]/flutter/bin"을 추가합니다. ([사용자 이름]은 실제 사용자 이름으로 변경하고, Flutter SDK 경로도 실제 경로로 변경해야 합니다.) Ctrl + X를 누르고,Y를 눌러 저장하고,Enter를 눌러 텍스트 편집기를 닫습니다.source ~/.bash_profile또는source ~/.zshrc명령어를 입력하여 변경된 환경 변수를 적용합니다.
- Linux:
- 터미널을 엽니다.
nano ~/.bashrc또는nano ~/.zshrc명령어를 입력하여 텍스트 편집기를 엽니다. (사용하는 쉘에 따라 파일 이름이 다를 수 있습니다.)- 파일의 맨 아래에
export PATH="$PATH:~/flutter/bin"을 추가합니다. (Flutter SDK 경로도 실제 경로로 변경해야 합니다.) Ctrl + X를 누르고,Y를 눌러 저장하고,Enter를 눌러 텍스트 편집기를 닫습니다.source ~/.bashrc또는source ~/.zshrc명령어를 입력하여 변경된 환경 변수를 적용합니다.
터미널 재시작 및 Flutter Doctor 실행
PATH 환경 변수를 설정한 후에는 반드시 터미널 또는 명령 프롬프트를 재시작해야 합니다. 기존에 열려 있던 터미널은 변경된 환경 변수를 인식하지 못하기 때문입니다. 터미널을 재시작한 후, flutter doctor 명령어를 입력하여 Flutter가 제대로 설치되었는지 확인해 보세요. flutter doctor는 Flutter 개발에 필요한 도구들이 제대로 설치되어 있는지, 환경 설정은 올바르게 되어 있는지 등을 검사하고, 문제점이 있다면 해결 방법을 제시해 주는 유용한 명령어입니다.
만약 flutter doctor 실행 결과에 오류 메시지가 나타난다면, 메시지를 자세히 읽어보고 제시된 해결 방법을 따라 문제를 해결해 주세요. 예를 들어, Android SDK가 설치되지 않았거나, 라이선스에 동의하지 않았다는 메시지가 나타날 수 있습니다. 이러한 경우에는 Android Studio를 설치하거나, flutter doctor --android-licenses 명령어를 실행하여 라이선스에 동의해야 합니다.
문제 해결 및 추가 팁
위의 방법들을 따라 했음에도 불구하고 여전히 문제가 해결되지 않는다면, 다음과 같은 추가적인 해결 방법을 시도해 볼 수 있습니다.
- 오타 확인: PATH 환경 변수를 설정할 때 오타가 없는지 꼼꼼하게 확인해 주세요. 특히, 경로 구분자 (Windows에서는
\, macOS 및 Linux에서는/)를 잘못 사용하거나, 공백이 포함되어 있는지 확인해야 합니다. - 관리자 권한 실행: 터미널 또는 명령 프롬프트를 관리자 권한으로 실행하여 명령어를 실행해 보세요. 특히, Windows에서는 일부 명령어가 관리자 권한으로 실행되어야 제대로 작동하는 경우가 있습니다.
- IDE 재시작: Visual Studio Code나 Android Studio와 같은 IDE를 사용하고 있다면, IDE를 재시작하여 변경된 환경 변수를 적용해 보세요.
- Flutter SDK 재설치: 모든 방법을 시도해 봤지만 문제가 해결되지 않는다면, Flutter SDK를 삭제하고 다시 설치해 보는 것도 좋은 방법입니다.
Flutter 개발 환경을 설정하는 과정은 처음에는 다소 복잡하게 느껴질 수 있지만, 차근차근 단계를 따라가면 누구나 성공적으로 구축할 수 있습니다. 이 글에서 제시된 해결 방법들을 통해 여러분이 Flutter 개발 여정을 성공적으로 시작할 수 있기를 바랍니다. 혹시 더 궁금한 점이 있다면 언제든지 질문해 주세요!