맥북에서 VSCode를 설치한 뒤 가장 먼저 막히는 곳이 바로 터미널입니다. 앱은 잘 열리는데 VSCode 터미널 안에서는 명령어가 안 먹고, 한글이 깨지거나, 방금 설치한 도구가 command not found로 나오는 일이 생각보다 흔합니다. 특히 zsh 설정과 PATH 문제를 한 번에 정리하지 않으면 이후 Git, Node.js, Python 세팅에서도 계속 같은 문제를 반복하게 됩니다.
이 글은 초보자 기준으로 VSCode 터미널을 안정적으로 쓰기 위한 핵심만 모았습니다. 기본 셸 확인, zsh 설정, 폰트 선택, 한글 깨짐 대응, 경로(PATH) 문제 점검, 그리고 자주 나오는 오류 해결 순서까지 그대로 따라 하면 됩니다. 한 번만 정리해 두면 이후 개발환경 세팅 속도가 확실히 빨라집니다.
왜 VSCode 터미널에서 먼저 막힐까?
VSCode 터미널은 단순히 검은 창이 아니라, macOS의 셸 환경과 VSCode 설정이 만나는 지점입니다. 그래서 같은 맥북이라도 터미널 앱에서는 잘 되는데 VSCode 안에서는 다르게 동작할 수 있습니다. 이때 대부분 원인은 세 가지입니다. 첫째, 로그인 셸과 비로그인 셸 차이. 둘째, zsh 설정 파일의 적용 범위 차이. 셋째, 설치된 프로그램의 PATH 문제입니다.
- VSCode에서는 터미널 프로필이 따로 잡혀 있을 수 있습니다.
.zprofile,.zshrc중 어디에 설정했는지에 따라 적용 결과가 달라집니다.- 폰트가 맞지 않으면 아이콘, 특수문자, 한글 정렬이 어긋납니다.
- Homebrew, nvm, pyenv를 설치해도 PATH가 안 잡히면 명령어를 못 찾습니다.
| 증상 | 가장 흔한 원인 | 먼저 볼 것 |
|---|---|---|
| command not found | PATH 미적용 | echo $PATH |
| 한글 깨짐 | 폰트/인코딩 문제 | 터미널 폰트 설정 |
| 프롬프트가 이상함 | zsh 설정 충돌 | .zshrc 내용 |
| VSCode에서만 명령어 불가 | 셸 초기화 파일 범위 차이 | .zprofile, .zshrc |
1단계: VSCode 터미널 기본 상태부터 확인하기
현재 어떤 셸을 쓰는지 확인
가장 먼저 VSCode에서 새 터미널을 열고 아래 명령으로 현재 셸을 확인하세요. macOS 기본은 보통 zsh이지만, 예전 환경을 옮겨온 경우 bash나 다른 셸이 잡혀 있을 수 있습니다.
echo $SHELL
echo $0VSCode 기본 터미널 프로필 점검
Command Palette에서 Terminal: Select Default Profile을 실행한 뒤 zsh가 기본으로 선택되어 있는지 확인합니다. 이후 터미널을 완전히 닫고 새로 열어야 반영됩니다. 이 단계가 꼬이면 VSCode 터미널에서만 다르게 보일 수 있습니다.
초보자 추천 기본 설정
- 기본 프로필은 zsh로 통일
- 복잡한 테마 적용 전 순정 상태에서 동작 확인
.zprofile에는 PATH 계열,.zshrc에는 별칭/프롬프트 위주로 분리- 설정 후 반드시 VSCode 전체 재실행
2단계: zsh 설정은 어디에 넣어야 할까?
zsh 설정에서 가장 많이 헷갈리는 부분이 바로 파일 역할입니다. 초보자는 모든 설정을 .zshrc 하나에 몰아넣는 경우가 많은데, 설치 경로나 PATH처럼 로그인 시점에 잡히는 값은 .zprofile에 두는 편이 안정적입니다. 반면 alias, 프롬프트, 자동완성 같은 상호작용 설정은 .zshrc가 잘 맞습니다.
| 파일 | 추천 용도 | 예시 |
|---|---|---|
~/.zprofile |
로그인 시 적용될 환경 변수 | PATH, Homebrew 경로 |
~/.zshrc |
터미널 사용 편의 설정 | alias, prompt, plugin |
안전한 최소 예시
# ~/.zprofile
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
# ~/.zshrc
alias ll="ls -al"
alias gs="git status"핵심은 zsh 설정을 화려하게 시작하지 않는 것입니다. 먼저 기본 경로가 안정적으로 잡히는지 확인하고, 그다음 테마나 플러그인을 추가하세요. 순서를 거꾸로 가면 오류 원인을 찾기가 훨씬 어려워집니다.
3단계: 폰트·한글 깨짐 문제 해결
VSCode 터미널에서 글자가 네모로 나오거나, 아이콘이 깨지거나, 한글 폭이 어긋나면 폰트부터 의심하는 것이 맞습니다. 개발용 폰트는 영문만 예쁘게 보이는 경우가 있고, Nerd Font 계열은 아이콘 표시에는 좋지만 한글 정렬에서는 환경에 따라 차이가 납니다. 그래서 초보자는 너무 특수한 폰트보다 검증된 조합으로 시작하는 편이 안전합니다.
추천 순서
- 1순위: 기본 모노스페이스 + 한글 표시 확인
- 2순위: MesloLGS NF, JetBrains Mono Nerd Font 등 아이콘 지원 폰트
- 3순위: 테마/프롬프트 플러그인 적용
VSCode에서 확인할 설정
"terminal.integrated.fontFamily": "MesloLGS NF, D2Coding, monospace",
"terminal.integrated.fontSize": 14,
"terminal.integrated.lineHeight": 1.2,
"terminal.integrated.gpuAcceleration": "auto"한글 깨짐이 있을 때는 폰트만 바꾸지 말고, 터미널을 새로 열어 비교해 보세요. 같은 설정이라도 기존 세션에서는 그대로 남아 있을 수 있습니다. 또한 프롬프트 테마가 특수문자를 많이 쓰는 경우, 폰트 호환성이 맞지 않으면 VSCode 터미널 전체가 지저분해 보일 수 있습니다.
4단계: PATH 문제를 가장 빠르게 잡는 방법
실전에서 가장 자주 만나는 것은 역시 PATH 문제입니다. Homebrew로 설치한 git, node, python이 터미널에서 안 잡히면 대부분 경로가 제대로 안 들어간 것입니다. 특히 Apple Silicon 맥은 /opt/homebrew/bin, Intel 맥은 /usr/local/bin 경로를 자주 확인하게 됩니다. 이 부분이 빠지면 VSCode 터미널에서는 설치한 도구가 없는 것처럼 보입니다.
먼저 실행할 점검 명령어
echo $PATH
which git
which node
which python3
printenv | grep PATH확인 포인트
/opt/homebrew/bin또는/usr/local/bin이 PATH 안에 있는지- nvm, pyenv를 쓰는 경우 초기화 구문이
.zshrc에 들어 있는지 - VSCode 재실행 후에도 동일한지
- 터미널 앱과 VSCode 결과가 같은지
경로(PATH) 문제는 “설치가 실패한 것”처럼 보이게 만든다는 점이 까다롭습니다. 실제로는 설치가 끝났는데 셸이 그 위치를 모르기 때문에 실행을 못 하는 것입니다. 그래서 무작정 재설치하기보다 현재 PATH를 먼저 보는 습관이 중요합니다. 이 습관 하나만 생겨도 PATH 문제 해결 속도가 훨씬 빨라집니다.
Homebrew 경로 예시
# Apple Silicon
export PATH="/opt/homebrew/bin:$PATH"
# Intel Mac
export PATH="/usr/local/bin:$PATH"5단계: 자주 막히는 오류 5가지와 바로 해결법
1. command not found
대부분 PATH 문제입니다. 설치 경로를 PATH에 추가했는지, 설정 파일을 저장했는지, VSCode를 완전히 재시작했는지 먼저 확인하세요.
2. code 명령이 터미널에서 안 됨
VSCode에서 Command Palette를 열고 Shell Command: Install 'code' command in PATH를 실행하면 해결되는 경우가 많습니다.
3. 한글 입력은 되는데 정렬이 이상함
폰트 호환성 문제일 가능성이 큽니다. 터미널 폰트를 바꾸고 lineHeight를 조정해 보세요. 복잡한 테마는 잠시 꺼두는 것이 좋습니다.
4. 프롬프트가 너무 느려짐
zsh 설정에 플러그인을 과하게 넣은 경우가 많습니다. 처음에는 alias 몇 개와 PATH만 두고 시작하는 편이 낫습니다.
5. 터미널 앱과 VSCode 결과가 다름
.zprofile와 .zshrc 적용 범위 차이를 점검하세요. 같은 명령어를 두 터미널에서 모두 실행해 비교하면 원인을 빨리 좁힐 수 있습니다.
6단계: 초보자용 추천 세팅 조합
처음부터 완벽한 터미널을 만들 필요는 없습니다. 오히려 VSCode 터미널은 최소 구성으로 시작할수록 문제를 잡기 쉽습니다. 제 추천은 zsh 기본 + Homebrew PATH + 가벼운 alias + 무난한 폰트 조합입니다. 이 구성만으로도 Git, Node.js, Python 대부분의 작업을 안정적으로 시작할 수 있습니다.
- 셸: zsh
- 환경 변수:
.zprofile에서 관리 - 사용 편의 설정:
.zshrc에서 관리 - 폰트: MesloLGS NF 또는 D2Coding 계열 혼합
- 확장 전제: Git, Node.js, Python 설치 후
which와 PATH로 검증
정리하면 zsh 설정은 단순하게, 폰트는 안정적으로, PATH 문제는 숫자처럼 확인 가능한 방식으로 접근하는 것이 핵심입니다. 감으로 만지기보다 echo $PATH, which, VSCode 재실행, 파일 역할 분리를 순서대로 점검하면 대부분의 문제는 예상보다 빨리 해결됩니다.
FAQ
마무리
VSCode 터미널은 개발 시작선입니다. 여기서 막히면 이후 Git, Node.js, Python 세팅도 줄줄이 느려집니다. 반대로 zsh 설정, 폰트, 한글 표시, 경로(PATH) 문제만 깔끔하게 정리해 두면 이후 작업이 훨씬 편해집니다. 오늘은 화려한 커스터마이징보다 “잘 작동하는 상태”를 먼저 만드는 데 집중해 보세요.
0 댓글