macOS에서 uv 설치 및 PATH 설정 가이드

이 문서는 macOS에서 uv를 설치하고 올바르게 PATH에 설정하여 항상 접근 가능하도록 만드는 방법을 설명합니다.

쉘 설정 파일 개요

macOS에서 사용되는 주요 쉘 설정 파일의 차이점은 다음과 같습니다:

.profile 파일 (예: .bash_profile, .zprofile)

로그인 세션에서만 로드됨 (사용자가 시스템에 로그인할 때)
환경 변수 설정, PATH 변수 등 세션 전체에 적용되는 설정에 적합
한 번만 실행되는 명령어나 환경 설정에 사용
GUI 로그인 시스템에서는 이 파일들이 로드됨

.rc 파일 (예: .bashrc, .zshrc)

모든 새로운 쉘 인스턴스(대화형 쉘)가 시작될 때마다 로드됨
별칭(alias), 함수 정의, 쉘 옵션 등 쉘 환경 설정에 적합
터미널 창을 열 때마다 실행됨
대화형 셸 설정에 주로 사용됨

macOS의 기본 쉘

macOS Catalina(10.15) 이후 버전에서는 기본 쉘이 bash에서 zsh로 변경되었습니다.
최신 macOS에서는 주로 .zshrc와 .zprofile 파일을 사용합니다.

uv 설치 및 PATH 설정 절차

1. uv 설치 확인

ls -la /Users/martin/.local/bin/uv

이 명령어로 uv가 설치되어 있는지 확인합니다.

2. PATH에 설치 경로 포함 여부 확인

echo $PATH | tr ':' '\n' | grep "/Users/martin/.local/bin"

결과가 나오면 이미 PATH에 포함되어 있는 것입니다.

3. 현재 사용 중인 쉘 확인

echo $SHELL

결과가 /bin/zsh이면 zsh를, /bin/bash이면 bash를 사용 중입니다.

4. 쉘 설정 파일 존재 여부 확인

# zsh 쉘인 경우
ls -la ~/.zshrc ~/.zprofile ~/.zshenv

# bash 쉘인 경우
ls -la ~/.bashrc ~/.bash_profile ~/.profile

5. 쉘 설정 파일에서 PATH 설정 확인

# zsh 쉘인 경우
grep -E "PATH=|path=" ~/.zshrc ~/.zprofile ~/.zshenv 2>/dev/null | grep ".local/bin"

# bash 쉘인 경우
grep -E "PATH=|path=" ~/.bashrc ~/.bash_profile ~/.profile 2>/dev/null | grep ".local/bin"

6. PATH 설정 추가

적절한 쉘 설정 파일에 PATH를 추가합니다:

# zsh 쉘인 경우 (일반적으로 ~/.zshrc에 추가)
echo 'export PATH="/Users/martin/.local/bin:$PATH"' >> ~/.zshrc

# 지속적인 효과를 위해 ~/.zprofile에도 추가
echo 'export PATH="/Users/martin/.local/bin:$PATH"' >> ~/.zprofile

# bash 쉘인 경우
echo 'export PATH="/Users/martin/.local/bin:$PATH"' >> ~/.bash_profile

7. 변경사항 즉시 적용

# 사용 중인 쉘에 따라 실행
source ~/.zshrc
# 또는
source ~/.bash_profile

8. 설정 적용 확인

which uv
echo $PATH | tr ':' '\n' | grep "/Users/martin/.local/bin"

which uv가 /Users/martin/.local/bin/uv를 반환하면 성공입니다.

9. 리부팅 후 지속성 확인

맥을 재부팅한 후 다음 명령어를 실행하여 설정이 유지되는지 확인하세요:

# uv 명령어가 정상적으로 실행되는지 확인
uv --version

# PATH에 필요한 경로가 포함되어 있는지 확인
echo $PATH | tr ':' '\n' | grep "/Users/martin/.local/bin"

리부팅 후에도 uv가 실행되지 않는다면:

.zprofile과 .zshrc 모두에 PATH 설정이 되어 있는지 확인하세요

전체 시스템에 적용하려면 (관리자 권한 필요):

sudo echo 'export PATH="/Users/martin/.local/bin:$PATH"' >> /etc/zshenv

문제 해결

PATH 설정 문제가 지속된다면 다음을 확인하세요:

파일 권한이 올바른지 확인:
```
chmod +x /Users/martin/.local/bin/uv
```
PATH 변수 설정 순서 확인 - macOS의 Path_helper는 때때로 PATH 순서를 변경할 수 있습니다.
모든 관련 쉘 설정 파일에 일관된 PATH 설정이 있는지 확인하세요.

.zshrc에 PATH를 추가하는 주된 이유는 다음과 같습니다:

대화형 쉘 세션에서의 접근성 - .zshrc는 새 터미널 창이나 탭을 열 때마다 로드됩니다. PATH를 여기에 추가하면 터미널에서 작업할 때 항상 해당 경로에 있는 명령어(예: uv)를 사용할 수 있습니다.
즉각적인 효과 - 변경 사항을 즉시 적용하기 위해 source ~/.zshrc를 실행하면 바로 PATH가 업데이트됩니다.
macOS의 터미널 동작 - macOS에서는 새 터미널 세션이 시작될 때 주로 .zshrc가 로드됩니다. 로그인 쉘이 아닌 대화형 쉘로 시작하는 경우가 많기 때문에 .zprofile만 설정하면 터미널에서 PATH가 인식되지 않을 수 있습니다.

그러나 완전한 지속성을 위해서는 .zshrc와 .zprofile 모두에 PATH를 설정하는 것이 좋습니다:

.zshrc: 터미널 세션에서의 즉각적인 사용성을 위해
.zprofile: 로그인 세션과 GUI 애플리케이션에서의 접근성을 위해 (시스템 재부팅 이후에도 유지)

hongsw/macos_path_setting.md