iTerm2 최초 설정 가이드 (macOS · Apple Silicon 기준)

본 문서는 팀 구성원이 그대로 따라 하면 동일한 환경을 재현할 수 있도록, iTerm2와 Zsh, 테마 및 개발 도구(Neovim/LazyVim) 초기 구성을 단계별로 정리합니다. 모든 명령은 복사–붙여넣기 후 실행 가능하도록 구성했습니다.

대상: macOS 13 이상(Apple Silicon 권장), iTerm2 사용자, Zsh 기본 쉘 환경, Homebrew가 사전에 설치된 환경범위: D2CodingLigature Nerd Font, iTerm2 Snazzy 컬러 테마, oh-my-zsh, ~/.zshrc.d 분할 로딩, nvm/pyenv 연동(선택), Neovim, LazyVim

0. iTerm2 설치 (사전 준비)

• 공식 사이트에서 iTerm2를 설치합니다. (App Store 버전보다 공식 DMG 권장)

• 설치 후 iTerm2를 기본 터미널로 사용합니다.

1. D2CodingLigature Nerd Font 설치 (Neovim/파워라인 글리프 용)

1. 릴리즈 페이지에서 최신 D2Coding.zip 다운로드

2. 압축을 풀고 모든 폰트 파일을 더블 클릭하여 설치

3. iTerm2 → Settings → Profiles → Default → Text → Font에서D2CodingLigature Nerd Font 선택

4. 하단 옵션에서 Use Ligatures 활성화(권장)

증상 해결: 프롬프트 기호, 파워라인 아이콘, Git 브랜치 표식 등이 깨지면 폰트 적용 여부를 재확인하십시오.

2. iTerm2 Snazzy 컬러 테마 적용

• 저장소: sindresorhus/iterm2-snazzy

• 설치 지침(원문 요약):

  1. 해당 저장소에서 Snazzy.itermcolors 파일을 우클릭 → Save Link As…로 저장

  2. 다운로드한 파일을 더블 클릭하여 iTerm2에 등록

  3. iTerm2 → Settings → Profiles → Default → Colors → Import…

  4. Snazzy.itermcolors 선택 후 목록에서 Snazzy 선택

  5. Modes: Use separate colors for light and dark mode 옵션 해제

Snazzy가 컬러로 적용되지 않으면:

• 프로파일이 Default인지 확인

• Colors 탭에서 Snazzy가 선택되어 있는지 확인

• Terminal 탭의 Report Terminal Type이 xterm-256color인지 확인

3. oh-my-zsh 설치 및 Agnoster 테마 적용 (강력 추천)

보안 고지: curl | sh 방식은 공식 저장소(ohmyzsh/ohmyzsh)에서만 사용하세요.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

설치가 완료되면 ~/.zshrc가 생성/갱신됩니다. 테마 설정을 아래와 같이 변경합니다.

# See https://github.com/ohmyzsh/ohmyzsh/wiki/Themes
ZSH_THEME="agnoster"

Agnoster 테마를 강력히 추천합니다. 파워라인 글리프를 지원하는 Nerd Font와 매우 잘 어울립니다.적용 방법: iTerm2를 완전히 종료 후 재시작하거나 source ~/.zshrc로 재적용.

4. Zsh 설정 분할: ~/.zshrc.d 디렉터리 도입

여러 도구별 설정을 파일로 분리하면 유지보수가 수월합니다.

mkdir -p ~/.zshrc.d

~/.zshrc의 하단에 다음 블록을 추가합니다.

# Load my configs
for config_file in $HOME/.zshrc.d/*.zsh; do
  source $config_file
done

적용:

source ~/.zshrc

이후 nvm/pyenv/nvim 등 각각의 설정은 ~/.zshrc.d/*.zsh 파일로 관리합니다.

5. (선택) nvm 연동

전제: 이미 nvm이 설치되어 있는 경우. (Homebrew로 설치한 경우 기준)

설정 파일 생성:

vi ~/.zshrc.d/nvm.zsh

다음 내용을 입력 후 저장:

# nvm
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"  # This loads nvm
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"  # This loads nvm bash_completion

권한 및 적용:

chmod 775 ~/.zshrc.d/nvm.zsh
source ~/.zshrc
nvm --version

참고: Homebrew가 아닌 스크립트 설치라면 nvm.sh 경로가 다를 수 있습니다. 아래 대체 구문을 사용하세요.
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

6. (선택) pyenv 연동

설정 파일 생성:

vi ~/.zshrc.d/pyenv.zsh

다음 내용을 입력 후 저장:

# pyenv
eval "$(pyenv init -)"

권한 및 적용:

chmod 775 ~/.zshrc.d/pyenv.zsh
source ~/.zshrc
pyenv -v

설치 팁(없다면):
brew install pyenv
brew install openssl readline sqlite3 xz zlib bzip2
Python 빌드 시 LDFLAGS/CPPFLAGS가 필요한 경우 pyenv 문서를 참고하십시오.

7. (권장) True Color 및 터미널 설정

Neovim 컬러스킴 호환을 위해 다음을 추가합니다.

vi ~/.zshrc.d/terminal.zsh
# Terminal capabilities
export TERM="xterm-256color"
export COLORTERM="truecolor"
chmod 775 ~/.zshrc.d/terminal.zsh
source ~/.zshrc

8. Neovim 설치 및 편의 별칭

Homebrew로 설치:

brew install neovim

별칭 설정:

vi ~/.zshrc.d/nvim.zsh
# nvim
alias vi="nvim"
alias vim="nvim"

적용:

chmod 775 ~/.zshrc.d/nvim.zsh
source ~/.zshrc
nvim --version

9. LazyVim 설치

사전 백업 및 초기화:

mv ~/.config/nvim{,.bak}
mkdir -p ~/.config/nvim

Starter 템플릿 클론:

git clone https://github.com/LazyVim/starter ~/.config/nvim
rm -rf ~/.config/nvim/.git

첫 실행(플러그인 설치 자동 진행):

nvim

설치가 느리거나 실패할 때
네트워크 상태 확인 후 재시도

:checkhealth로 의존성 점검

Tree-sitter 컴파일 문제 발생 시 Xcode CLT 설치: xcode-select --install

10. 문제 해결(FAQ)

• 테마가 적용되지 않음

  • iTerm2 완전 종료 후 재시작

  • ~/.zshrc의 ZSH_THEME 값 확인, source ~/.zshrc

  • 폰트가 파워라인/NERD를 지원하는지 재점검

• Snazzy가 목록에 안 보임

  • Snazzy.itermcolors를 Import했는지 확인

  • Profiles → Default 프로파일을 수정 중인지 확인

  • Light/Dark 분리 색상 옵션이 켜져 있으면 해제

• 글리프/아이콘이 깨짐

  • iTerm2 Text → Font에서 D2CodingLigature Nerd Font로 지정했는지 확인

  • Use Ligatures 활성화

  • 탭/윈도우별로 다른 프로파일을 쓰는 경우 각 프로파일에 동일하게 적용

• nvm 명령을 인식 못 함

  • ~/.zshrc.d/nvm.zsh의 경로가 환경에 맞는지(특히 Homebrew 경로 /opt/homebrew) 확인

  • echo $NVM_DIR 출력값 검증, 셸 재시작

• Neovim 색상이 이상함

  • 7장 설정대로 COLORTERM=truecolor 적용

  • iTerm2 Advanced에서 24-bit color 지원이 켜져 있는지 확인

11. 원복(되돌리기)

• LazyVim 제거:

  rm -rf ~/.config/nvim
  mv ~/.config/nvim.bak ~/.config/nvim  # 백업 복구(있는 경우)

• Zsh 분할 로딩 비활성화:

  • ~/.zshrc에서 ~/.zshrc.d/*.zsh 로딩 블록 제거

  • ~/.zshrc.d 디렉터리 삭제(선택)

• Snazzy 컬러 테마 미적용으로 되돌리기:

  • Profiles → Colors에서 다른 컬러 프리셋 선택

12. 검증 체크리스트

• echo $SHELL이 /bin/zsh 또는 Zsh인지 확인

• zsh --version 및 oh-my-zsh 폴더(~/.oh-my-zsh) 존재 확인

• iTerm2 Profiles → Colors에서 Snazzy 선택 및 Light/Dark 분리 옵션 해제

• iTerm2 Profiles → Text → Font에서 D2CodingLigature Nerd Font + Use Ligatures

• nvm --version / pyenv -v 정상 출력(선택)

• nvim --version 정상 출력, :checkhealth 통과

13. 부록: 팀 내 공유 시 권장 사항

• 이 문서를 레포지토리 루트의 docs/iterm2-setup.md로 두고, 변경 시 PR 리뷰를 거치십시오.

• 팀 표준 프로파일(예: 프롬프트, 별칭, 함수)은 ~/.zshrc.d/company.zsh 등 단일 파일로 배포하면 관리가 쉽습니다.

• 신규 입사자 온보딩 체크리스트에 1·2·3·4장을 필수 항목으로 포함하십시오.

참고 저장소

• oh-my-zsh: https://github.com/ohmyzsh/ohmyzsh

• iTerm2 Snazzy: https://github.com/sindresorhus/iterm2-snazzy

• Nerd Fonts: https://github.com/ryanoasis/nerd-fonts

• Neovim: https://neovim.io

• LazyVim: https://lazyvim.github.io

ps. 그냥 긁어서 붙인거라.. 링크나 이런게 제대로 동작하지 않을 수도 있습니다.