맥북 zsh command not found 해결법, PATH 5분 정리

맥북 터미널에서 zsh command not found가 뜨는 이유는 대부분 PATH 설정 한 줄 때문입니다. 원인별로 5분 안에 확인하고 고치는 순서를 정리합니다.

맥북 터미널에서 zsh: command not found 메시지가 뜨는 건 대부분 프로그램이 없어서가 아니라, 컴퓨터가 그 프로그램의 위치를 못 찾아서입니다. 이 글은 맥북 zsh command not found 오류를 원인별로 나눠 5분 안에 확인하고 고치는 순서를 정리합니다. 저도 처음엔 무작정 재설치만 반복하다가 시간을 꽤 버렸는데, 막상 원인은 설정 파일 한 줄이 빠진 경우가 많았습니다. 특히 개발을 막 시작한 분들은 "설치는 분명히 했는데 왜 안 되지?" 하고 당황하기 쉽습니다. 순서대로 따라오시면 대부분 풀립니다.

목차

1. 이 에러가 정확히 무슨 뜻인지부터
2. 먼저 확인할 것 3가지
3. 실제로 설치돼 있는지 확인하는 법
4. PATH에 폴더를 등록하는 방법
5. 자주 막히는 부분

이 에러가 정확히 무슨 뜻인지부터

zsh: command not found: xxx는 "xxx라는 명령어를 zsh가 찾을 수 있는 폴더 안에서 못 찾았다"는 뜻입니다.

여기서 잠깐 용어를 풀어드리면, 터미널은 검은 화면에 명령어를 입력해서 컴퓨터에게 직접 일을 시키는 프로그램입니다. macOS Catalina(2019) 이후로는 기본 셸이 zsh(지-셸)로 바뀌었는데, 셸은 터미널에 입력한 명령어를 해석해서 실행해주는 통역사 같은 역할을 합니다.

그리고 PATH(패스). 이게 이번 글의 주인공입니다.

PATH는 셸이 명령어를 찾을 때 뒤지는 폴더 목록입니다. 도서관에서 책을 찾을 때 "1층 A구역, 2층 B구역만 뒤져라"라고 정해둔 것과 비슷합니다. 아무리 책(프로그램)이 지하 창고에 있어도, 그 창고가 목록에 없으면 사서(zsh)는 "그런 책 없는데요"라고 답합니다. 그게 정확히 command not found의 상황입니다.

먼저 확인할 것 3가지

무작정 설정을 건드리기 전에 아래 순서대로 확인하면 원인을 좁힐 수 있습니다.

순서	확인할 것	왜
1	명령어 철자·대소문자	Python과 python은 다름
2	실제로 설치됐는지	which로 위치 조회
3	PATH에 그 폴더가 있는지	있으면 인식, 없으면 등록 필요

터미널을 열고 다음을 순서대로 입력해봅니다.

which python3

이 명령은 "python3이라는 명령어가 어느 폴더에 있는지 알려줘"라는 뜻입니다.

• 경로가 나오면(예: /usr/bin/python3) → 설치는 돼 있음. PATH 문제 아님. 다른 오타·별칭 문제일 확률
• python3 not found가 뜨면 → 정말 설치가 안 됐거나, 설치는 됐지만 PATH에 없음

설치는 됐는데 PATH에 없는 상황이 가장 흔합니다. 다음 섹션에서 다룹니다.

실제로 설치돼 있는지 확인하는 법

프로그램이 설치돼 있는지는 예상되는 폴더를 직접 뒤져보면 알 수 있습니다. 맥에서 개발 도구가 주로 설치되는 폴더는 다음과 같습니다.

폴더	주로 무엇이 들어감
/usr/local/bin	인텔 맥의 Homebrew, 수동 설치 도구
/opt/homebrew/bin	애플 실리콘(M1~M4) Homebrew
~/.nvm/versions/node/...	nvm으로 설치한 Node.js
/usr/bin	macOS 기본 제공 도구

예를 들어 brew(Homebrew, 맥에서 개발 도구를 설치·관리하는 패키지 매니저) 명령이 안 잡힌다면, M1~M4 맥에서는 실제로는 /opt/homebrew/bin/brew에 파일이 있을 확률이 높습니다.

확인은 이렇게 합니다.

ls /opt/homebrew/bin/brew

파일이 있다는 응답이 나오면 설치는 정상. 이제 이 폴더를 PATH에 등록만 해주면 됩니다.

💡 애플 실리콘 맥(M1 이후)과 인텔 맥은 Homebrew 설치 위치가 다릅니다. 인터넷 예전 글을 그대로 따라 하면 경로가 안 맞는 경우가 많으니, 본인 맥이 어느 쪽인지 먼저 확인하세요. (좌측 상단 사과 → 이 Mac에 관하여 → 칩 항목)

PATH에 폴더를 등록하는 방법

zsh는 시작할 때 ~/.zshrc라는 설정 파일을 읽습니다. 여기에 "이 폴더도 뒤져줘"라는 한 줄을 추가하면 됩니다.

터미널에서 다음을 입력합니다.

open -e ~/.zshrc

이 명령은 홈 폴더의 .zshrc 파일을 텍스트 편집기로 여는 겁니다. 파일이 없다는 에러가 뜨면, 먼저 아래로 파일을 만든 뒤 다시 실행합니다.

touch ~/.zshrc

파일이 열리면 맨 아래에 다음 한 줄을 추가합니다. (애플 실리콘 맥에서 Homebrew를 쓰는 경우 예시)

export PATH="/opt/homebrew/bin:$PATH"

이 줄의 뜻을 풀어드리면 — "기존 PATH 목록 맨 앞에 /opt/homebrew/bin 폴더를 추가해라"입니다. 맨 앞에 두는 이유는, 같은 이름의 명령이 여러 곳에 있을 때 이 폴더를 먼저 찾게 하기 위해서입니다.

저장하고 편집기를 닫은 뒤, 터미널에 다음을 입력합니다.

source ~/.zshrc

source는 "이 설정 파일을 지금 즉시 다시 읽어들여라"라는 명령입니다. 터미널을 껐다 켜도 같은 효과지만, 이게 더 빠릅니다.

이제 다시 원래 안 되던 명령어를 실행해보세요. 대부분 잡힙니다.

자주 막히는 부분

직접 여러 번 겪어본 함정 몇 가지를 정리합니다.

1. .zshrc를 저장한 뒤에도 안 되는 경우

source ~/.zshrc를 안 했거나, 편집기에서 저장이 안 된 경우가 대부분입니다. 저는 세 번째 시도에서야 저장 안 된 걸 발견한 적이 있습니다. 터미널을 완전히 껐다가 다시 여는 것도 확실한 방법입니다.

2. 따옴표·특수문자 오타

export PATH= 뒤에 큰따옴표를 빠뜨리거나, 콜론(:)이 아니라 세미콜론(;)을 넣으면 PATH 전체가 망가집니다. 이 상태에서는 ls 같은 기본 명령까지 안 먹습니다. 당황하지 말고 다음처럼 임시로 복구합니다.

export PATH=/usr/bin:/bin:/usr/sbin:/sbin

이 한 줄을 붙여넣으면 현재 세션의 PATH가 기본값으로 돌아옵니다. 그다음 다시 open -e ~/.zshrc로 열어 오타를 고치세요.

3. .bash_profile에만 등록돼 있는 경우

옛날 자료를 보고 따라 하면 .bash_profile에 PATH를 넣으라고 나옵니다. bash와 zsh는 읽는 파일이 다르기 때문에, zsh를 쓰는 지금은 그 설정이 무시됩니다. 맥에서 셸이 뭔지는 이렇게 확인합니다.

echo $SHELL

/bin/zsh가 나오면 .zshrc에 넣어야 맞습니다.

4. nvm·pyenv 같은 버전 관리 도구를 쓰는 경우

Node.js를 nvm(엔브이엠, Node.js 버전을 여러 개 깔아놓고 골라 쓰는 도구)으로 설치했다면, 단순히 폴더 하나 추가하는 걸로는 안 됩니다. 공식 문서에서 안내하는 초기화 스크립트 두세 줄을 .zshrc에 넣어야 합니다. 이 경우 오류 메시지에 "nvm command not found"가 뜬다면 nvm 자체가 등록 안 된 것이니, nvm 공식 GitHub의 설치 안내를 다시 확인하는 게 빠릅니다.

그래도 안 될 때 마지막 점검

여기까지 해도 안 잡히면 아래 체크리스트를 순서대로 봅니다.

• ☐echo $PATH로 현재 PATH 목록 출력해서 등록하려던 폴더가 실제로 들어가 있는지 눈으로 확인
• ☐ls [해당 폴더]로 그 폴더 안에 진짜로 실행 파일이 있는지 확인
• ☐파일이 있다면 ls -l로 실행 권한(x 표시)이 있는지 확인
• ☐터미널 앱을 완전히 종료(⌘+Q)했다가 다시 열기
• ☐그래도 안 되면 프로그램 자체를 재설치

특히 echo $PATH 결과를 눈으로 확인하는 습관은 시간을 많이 아껴줍니다. 콜론(:)으로 구분된 폴더 목록이 쭉 나오는데, 여기에 원하는 폴더가 없으면 100% PATH 등록 문제입니다.

정리하고 넘어가기

zsh: command not found는 대부분 "프로그램이 없다"가 아니라 "위치를 못 찾는다"의 문제입니다. 순서는 이렇게 잡으면 됩니다.

1. which 명령어로 찾을 수 있는지 확인
2. 안 찾아지면 예상 폴더에 실제 파일이 있는지 ls로 확인
3. 있으면 ~/.zshrc에 export PATH="폴더경로:$PATH" 추가
4. source ~/.zshrc로 반영
5. echo $PATH로 등록 여부 재확인

한 번 이 흐름을 이해하면, 앞으로 Homebrew·Node.js·Python·Go 어떤 걸 새로 설치하든 같은 방식으로 풉니다. 이번에 5분 투자해두면 두고두고 쓰는 지식이 됩니다.

함께 보면 좋은 글

• VS Code 한글 깨짐·폰트 문제 해결법 5가지 정리
• VS Code Tab 자동완성 안 될 때 원인과 해결법 7가지
• Claude Code "command not found" 에러 해결법 7가지