Homebrew로 git이나 python3를 설치했는데 터미널에서는 /usr/bin에 있는 Apple 기본 버전이 실행되는 경우가 있습니다. 또는 tmux 창을 나눌 때마다 echo $PATH에 같은 경로가 하나씩 더 붙습니다.
두 증상 모두 zsh가 시작 파일을 읽는 순서와, 그 중간에 macOS의 path_helper가 PATH를 다시 짜는 동작을 알면 설명이 됩니다. 어느 파일에 무엇을 둘지만 정리하면 해결됩니다.
지금 어떤 파일이 실행되는지 확인
# 이 이름으로 찾을 수 있는 실행 파일을 PATH 순서대로 모두 표시
type -a python3 git
# PATH를 한 줄에 하나씩
print -l $path
# 중복된 항목만
print -l $path | sort | uniq -d
zsh에서는 소문자 path 배열과 대문자 PATH 문자열이 연결돼 있어서 print -l $path로 보면 읽기 편합니다. type -a 결과의 첫 줄이 실제로 실행되는 파일입니다.
zsh가 시작 파일을 읽는 순서
로그인 셸로 시작할 때 zsh는 다음 순서로 파일을 읽습니다. 대화형이 아닌 셸(zsh -c '...')은 zshenv 계열만 읽습니다.
/etc/zshenv,~/.zshenv: 모든 zsh/etc/zprofile,~/.zprofile: 로그인 셸/etc/zshrc,~/.zshrc: 대화형 셸/etc/zlogin,~/.zlogin: 로그인 셸
macOS에서 중요한 것은 2번입니다. /etc/zprofile에는 path_helper를 실행하는 코드가 들어 있습니다. 그리고 macOS의 Terminal과 iTerm2는 새 창을 기본적으로 로그인 셸로 엽니다. tmux도 새 창과 패널을 로그인 셸로 띄웁니다. 즉 창을 열 때마다 path_helper가 실행됩니다.
path_helper가 순서를 바꾸는 방식
path_helper는 /etc/paths와 /etc/paths.d/ 아래 파일에 적힌 경로로 새 PATH를 만들고, 기존 PATH에 있던 나머지 경로는 그 뒤에 붙입니다. 시스템 경로가 항상 앞에 오게 되는 셈입니다.
그래서 ~/.zshenv에서 /opt/homebrew/bin을 맨 앞에 넣어 두면, 그 뒤에 실행되는 /etc/zprofile이 /usr/bin을 앞으로 끌어와 Homebrew 경로를 뒤로 밀어냅니다. ~/.zshrc에서 export PATH="/opt/homebrew/bin:$PATH"로 앞에 붙이는 방식은 순서는 맞지만, 이미 PATH를 물려받은 tmux나 하위 셸에서 다시 실행될 때마다 같은 경로가 하나씩 더 붙습니다.
결론은 사용자 경로를 path_helper 다음에 실행되는 ~/.zprofile에 두고, 중복은 zsh가 걸러 내게 하는 것입니다.
~/.zprofile 정리
# ~/.zprofile
# path 배열에서 중복을 자동으로 제거 (처음 나온 항목만 남김)
typeset -U path PATH
# Homebrew: Apple Silicon은 /opt/homebrew, Intel은 /usr/local
if [[ -x /opt/homebrew/bin/brew ]]; then
eval "$(/opt/homebrew/bin/brew shellenv)"
elif [[ -x /usr/local/bin/brew ]]; then
eval "$(/usr/local/bin/brew shellenv)"
fi
# 직접 관리하는 경로를 맨 앞에
path=("$HOME/.local/bin" "$HOME/bin" $path)
export PATH
typeset -U는 배열에서 같은 값이 다시 나오면 뒤의 것을 지웁니다. 사용자 경로를 앞에 붙인 다음 중복을 지우면, path_helper가 뒤쪽에 남겨 둔 같은 경로는 사라지고 앞쪽 것만 남습니다. 순서와 중복이 한 번에 정리됩니다. brew shellenv는 Homebrew 공식 문서가 안내하는 방법으로, 설치 위치에 맞는 PATH, MANPATH 등을 설정해 줍니다.
~/.zshrc에는 PATH를 앞에 붙이는 코드를 두지 않고 별칭, 프롬프트, 자동 완성처럼 대화형 셸에 필요한 설정만 둡니다. 도구 설치 스크립트가 ~/.zshrc 끝에 PATH 줄을 추가해 두는 경우가 많으니 한 번 훑어보고 ~/.zprofile로 옮깁니다. 옮기기 어려운 줄이 남는다면 ~/.zshrc 맨 위에도 typeset -U path PATH를 둬서 중복만이라도 막습니다.
새 창을 열어 결과를 봅니다.
print -l $path | head -5
print -l $path | sort | uniq -d # 아무것도 안 나오면 중복 없음
which -a git
터미널 밖에서 실행되는 경우
GUI 앱은 셸 시작 파일을 읽지 않고 launchd에서 기본 환경만 물려받습니다. 그래서 Dock에서 실행한 IDE가 내장 터미널이나 빌드 도구에서 다른 PATH를 쓰는 일이 생깁니다.
VS Code는 시작할 때 사용자의 로그인 셸을 한 번 실행해 환경 변수를 읽어 오고, macOS에서는 내장 터미널도 기본적으로 로그인 셸(-l)로 엽니다. ~/.zprofile에 정리해 두면 대부분 그대로 반영됩니다. IDE 설정에서 터미널 실행 인자를 바꿔 두었다면 -l이 빠지지 않았는지 확인합니다. JetBrains IDE도 셸 환경을 읽어 오는 방식이 비슷합니다.
/etc/zprofile을 직접 고치거나 path_helper를 지우는 방법은 권하지 않습니다. macOS 업데이트 때 원래대로 돌아가는 경우가 많고, 설치 프로그램들이 /etc/paths.d/에 등록하는 경로(예: Wireshark, MacTeX)도 같이 빠집니다. 사용자 파일에서 순서만 바로잡는 쪽이 오래 유지됩니다.
cron이나 launchd 에이전트로 실행하는 스크립트는 로그인 셸이 아니어서 ~/.zprofile도 읽지 않습니다. 이런 스크립트 안에서는 필요한 경로를 직접 지정하거나 /opt/homebrew/bin/python3처럼 절대 경로로 실행하는 편이 확실합니다.

