zsh 터미널, oh-my-zsh 테마 적용 어려울 때

zsh 터미널을 멋지게 꾸미고 싶은 마음에 oh-my-zsh를 설치했지만, 원하는 테마를 적용하려 할 때마다 복잡한 설정 파일 앞에서 막막함을 느끼셨을 겁니다.

함께 보면 좋은 글: 맥 터미널 글씨 안 보여? 폰트 크기 쉽게 키우기

수많은 옵션과 생소한 문법 때문에 테마 하나 바꾸는 일이 숙제처럼 느껴지셨을 텐데요.

이 글에서는 oh-my-zsh 테마 적용을 방해하는 흔한 문제들을 정확히 짚어내고, 초보자도 쉽게 따라 할 수 있는 세 가지 명확한 해결책을 제시하여 여러분의 터미널을 원하는 모습으로 완성하도록 돕겠습니다.

oh-my-zsh 테마 적용, 왜 어려울까요?

oh-my-zsh는 zsh 셸을 위한 프레임워크로, 수백 가지의 테마와 플러그인을 통해 터미널 환경을 개인화할 수 있게 해줍니다. 하지만 이 강력한 기능 뒤에는 몇 가지 함정이 숨어 있습니다. 가장 흔하게 발생하는 문제는 `.zshrc` 설정 파일의 문법 오류나 잘못된 테마 이름 입력입니다.

예를 들어, 테마 이름을 오타 내거나, 설정 파일의 다른 부분을 건드려 zsh 셸 자체가 시작되지 않는 상황도 발생할 수 있습니다. 실제 사용자 후기에서도 이러한 어려움을 토로하는 경우가 많습니다. "여기서 iTerm2에 Oh My Zsh를 깔고 그টাইমস 위에 테마를 입혀서 꾸미는 걸 보여주더라고요 터미널 쓸 일이 많았는데 여태 순정 터미널만 써온 터라 주말에 시간 잡고 따라해봤습니다." (출처: clien.net)

또한, 특정 테마는 최신 zsh 버전이나 특정 플러그인과의 호환성 문제가 있을 수 있습니다. 이러한 경우, 테마 적용 시 예상치 못한 오류가 발생하거나, 터미널이 비정상적으로 동작할 수 있습니다. 이러한 문제들은 일반적으로 3가지 주요 원인으로 귀결됩니다.

첫째, `.zshrc` 설정 파일의 구문 오류입니다. 복사 붙여넣기 과정에서 발생한 공백 문자나 잘못된 기호 등이 zsh 셸의 정상적인 실행을 방해합니다. 둘째, 테마 이름의 오타 또는 존재하지 않는 테마 지정입니다. oh-my-zsh는 지정된 테마를 찾지 못하면 기본 테마로 돌아가거나 오류를 발생시킵니다. 셋째, 테마 자체의 버그 또는 다른 플러그인과의 충돌입니다. 특히 복잡한 기능을 가진 테마일수록 이러한 문제가 발생할 확률이 높습니다.

Photo by Tima Miroshnichenko on Pexels

첫 번째 해결책: `.zshrc` 파일 직접 수정

oh-my-zsh 테마 적용의 핵심은 `.zshrc` 설정 파일을 올바르게 수정하는 것입니다. 이 파일은 zsh 셸이 시작될 때마다 실행되는 스크립트를 담고 있으며, 테마 설정 또한 이곳에서 이루어집니다. 대부분의 테마 적용 문제는 이 파일의 `ZSH_THEME` 변수를 잘못 건드렸을 때 발생합니다.

먼저, 터미널을 열고 다음 명령어를 입력하여 `.zshrc` 파일을 엽니다. `nano` 또는 `vim`과 같은 텍스트 에디터를 사용할 수 있습니다. 여기서는 `nano`를 예시로 들겠습니다. 만약 `.zshrc` 파일이 존재하지 않는다면, 홈 디렉토리에 해당 파일을 새로 생성해야 합니다.

nano ~/.zshrc

파일이 열리면, `ZSH_THEME=`로 시작하는 줄을 찾습니다. 이 줄에 현재 적용되어 있는 테마 이름이 큰따옴표 안에 적혀 있을 것입니다. 예를 들어, 기본 테마인 "robbyrussell"이 적용되어 있다면 다음과 같이 보일 것입니다.

ZSH_THEME="robbyrussell"

이제 원하는 테마로 변경하고 싶다면, 큰따옴표 안의 테마 이름을 원하는 테마의 실제 이름으로 바꾸면 됩니다. 예를 들어, "agnoster" 테마를 적용하고 싶다면 다음과 같이 수정합니다.

ZSH_THEME="agnoster"

테마 이름을 변경한 후에는 파일을 저장하고 닫습니다. `nano` 에디터에서는 `Ctrl+X`를 누르고 `Y`를 눌러 저장한 뒤 `Enter`를 누르면 됩니다. 변경 사항을 적용하기 위해 터미널을 다시 시작하거나, 다음 명령어를 실행합니다.

source ~/.zshrc

만약 이 과정에서 "command not found: zsh"와 같은 오류가 발생한다면, zsh 셸 자체가 제대로 설치되지 않았거나 시스템의 기본 셸이 zsh로 설정되지 않은 경우입니다. macOS에서는 `chsh -s /bin/zsh` 명령어로 기본 셸을 변경할 수 있습니다. Linux 환경에서는 배포판마다 명령어가 다를 수 있으니 해당 배포판의 문서를 참고해야 합니다.

주의: `.zshrc` 파일에는 테마 설정 외에도 다양한 사용자 정의 설정이 포함될 수 있습니다. 다른 설정을 건드리지 않고 `ZSH_THEME` 줄만 정확히 수정하는 것이 중요합니다. 실수로 다른 부분을 수정하여 터미널이 작동하지 않게 된다면, 이전 상태로 복구하기 어려울 수 있습니다. 중요한 설정 변경 전에는 항상 `.zshrc` 파일을 백업하는 습관을 들이는 것이 좋습니다. `cp ~/.zshrc ~/.zshrc_backup_$(date +%Y%m%d_%H%M%S)` 와 같은 명령어로 백업할 수 있습니다.

두 번째 해결책: 테마 호환성 확인 및 필수 플러그인 설정

모든 테마가 모든 환경에서 완벽하게 작동하는 것은 아닙니다. 일부 테마는 특정 폰트나 플러그인을 필요로 하며, 이를 충족하지 못하면 정상적으로 표시되지 않거나 오류를 발생시킬 수 있습니다. 특히 Powerline 폰트나 Nerd 폰트와 같이 특수 문자를 포함하는 폰트를 요구하는 테마들이 많습니다.

예를 들어, "agnoster" 테마는 기본적으로 Git 정보, 작업 디렉토리, 사용자 정보 등을 아이콘과 함께 표시해주지만, 이를 제대로 보기 위해서는 Powerline 폰트 설치가 필수적입니다. 만약 폰트가 설치되지 않았다면, 프롬프트가 깨져 보이거나 알 수 없는 문자들이 나타날 수 있습니다. 이 문제를 해결하기 위해선 먼저 시스템에 해당 폰트를 설치해야 합니다.

macOS에서는 Homebrew를 사용하여 폰트를 설치할 수 있습니다. 터미널에 다음 명령어를 입력하여 Powerline 폰트를 설치합니다.

brew tap homebrew/cask-fonts
brew install --cask font-powerline

Linux에서는 각 배포판의 패키지 관리자를 사용하거나, 폰트 파일을 직접 다운로드하여 설치해야 합니다. 설치 후에는 사용하는 터미널 에뮬레이터(iTerm2, VS Code 터미널, GNOME Terminal 등)의 설정을 변경하여 해당 폰트를 기본 폰트로 지정해야 합니다.

테마가 특정 플러그인을 요구하는 경우도 있습니다. oh-my-zsh의 플러그인 설정은 `.zshrc` 파일의 `plugins=( ... )` 부분에서 관리됩니다. 예를 들어, `zsh-autosuggestions`나 `zsh-syntax-highlighting`과 같은 플러그인은 zsh의 기능을 크게 향상시키는데, 일부 테마는 이러한 플러그인이 활성화되어 있을 때 더 잘 작동하도록 설계되었습니다.

만약 특정 테마 적용 후 Git 관련 정보가 제대로 표시되지 않는다면, `plugins=(git)` 부분이 `.zshrc` 파일에 제대로 포함되어 있는지 확인해야 합니다. 테마 문서에 명시된 필수 플러그인이 있다면, 해당 플러그인을 `plugins` 배열에 추가해야 합니다. 예를 들어, Git 정보 표시를 위한 `git` 플러그인을 추가하려면 다음과 같이 설정합니다.

plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

실용 팁: 테마를 설치하기 전에 해당 테마의 GitHub 저장소나 공식 문서를 확인하여 필요한 폰트나 플러그인 요구 사항을 미리 파악하는 것이 좋습니다. 대부분의 인기 있는 테마는 README 파일에 이러한 정보를 상세히 제공합니다. 예를 들어, Starship 테마는 특정 폰트 요구 사항이 없지만, 다른 테마들은 폰트 설치를 명시적으로 권장하거나 요구합니다. M3 칩셋을 탑재한 최신 맥북에서도 폰트 호환성은 중요합니다.

세 번째 해결책: 테마 오류 메시지 분석 및 해결

테마를 적용할 때 터미널에 나타나는 오류 메시지는 문제 해결의 가장 중요한 단서입니다. 오류 메시지를 무시하고 넘어가면 근본적인 문제를 해결할 수 없습니다. 오류 메시지를 주의 깊게 읽고, 어떤 부분이 잘못되었는지 파악하는 것이 중요합니다.

가장 흔하게 볼 수 있는 오류 메시지 중 하나는 `unknown option` 또는 `invalid option`과 같은 구문 오류 관련 메시지입니다. 이는 `.zshrc` 파일의 zsh 문법이 잘못되었거나, 테마 스크립트 자체에 문제가 있음을 나타냅니다. 예를 들어, `zsh: command not found: __git_ps1`과 같은 메시지는 `git` 플러그인이 제대로 로드되지 않았거나, `git` 플러그인에서 사용하는 함수가 정의되지 않았을 때 발생할 수 있습니다.

이 경우, 다음과 같은 단계를 따라 문제를 해결할 수 있습니다. 첫째, `.zshrc` 파일에서 `ZSH_THEME` 줄을 주석 처리하거나 기본 테마(`robbyrussell`)로 임시 변경하여 zsh 셸이 정상적으로 실행되는지 확인합니다. 만약 기본 테마로도 문제가 발생한다면, `.zshrc` 파일 전체에 심각한 문법 오류가 있을 가능성이 높습니다. 둘째, 오류 메시지에 언급된 특정 함수나 파일 경로를 검색하여 해당 문제가 어떤 부분과 관련 있는지 파악합니다. 예를 들어, `zsh: parse error near `fi''`와 같은 메시지는 `if` 문의 `fi`가 누락되었거나, 잘못된 위치에 있다는 것을 의미합니다.

어떤 사용자들은 원격 접속 시 zsh 터미널의 반응 속도가 느려질까 걱정하기도 합니다. "2. 원격접속으로 사용할떄 접속할 서버에서 zsh을 사용하면 터미널의 반응속도가 많이 느려지지는 않을까요? ... 1. Shell이기 때문에 아마 폰트만 준비되면 괜찮습니다. 2. 네트워크가 너무 느리지만 않으면 괜찮더군요. 애저 기준입니다. ... 위에 설지 방법대로" (출처: clien.net) 실제로, 일부 복잡한 테마나 과도한 플러그인은 원격 환경에서 성능 저하를 유발할 수 있습니다. 이럴 때는 테마를 더 가볍고 단순한 것으로 변경하거나, 사용하지 않는 플러그인을 비활성화하는 것이 해결책이 될 수 있습니다.

주의: 테마를 변경한 후 터미널을 열었을 때 아무것도 표시되지 않거나, 커서만 깜빡이는 증상이 나타난다면 `.zshrc` 파일에 치명적인 오류가 발생했을 가능성이 높습니다. 이 경우, 터미널에서 `export SHELL=/bin/bash`와 같은 명령어를 사용하여 임시로 bash 셸로 전환한 후, `.zshrc` 파일을 수정해야 할 수 있습니다. 또는 복구 모드나 다른 터미널 에뮬레이터를 사용하여 `.zshrc` 파일을 수정해야 할 수도 있습니다. Linux 시스템에서는 `Ctrl+Alt+F1`~`F6`을 눌러 가상 콘솔로 전환하여 복구 작업을 진행할 수 있습니다. macOS에서는 복구 모드로 진입하는 방법이 다릅니다.

실전: 나만의 터미널 테마 만들기

oh-my-zsh의 가장 큰 장점 중 하나는 단순히 기존 테마를 사용하는 것을 넘어, 자신만의 테마를 만들거나 기존 테마를 수정할 수 있다는 점입니다. 수백 가지의 테마를 탐색하는 것도 좋지만, 직접 원하는 스타일을 구현하는 것은 훨씬 더 만족스러운 경험을 제공합니다.

나만의 테마를 만들기 위해서는 zsh의 프롬프트 커스터마이징 기능과 oh-my-zsh의 테마 구조를 이해해야 합니다. oh-my-zsh의 테마는 기본적으로 `~/.oh-my-zsh/themes/` 디렉토리에 `.zsh-theme` 확장자를 가진 파일들로 구성됩니다. 새로운 테마를 만들고 싶다면, 이 디렉토리에 새로운 `.zsh-theme` 파일을 생성하고 원하는 zsh 프롬프트 코드를 작성하면 됩니다.

zsh 프롬프트는 `PS1` 환경 변수에 의해 제어됩니다. `PS1`은 다양한 이스케이프 시퀀스와 zsh 내장 기능을 사용하여 동적으로 구성될 수 있습니다. 예를 들어, `%(?..%F{red}%n@%F{green}%m %F{blue}%~%f) %#` 와 같은 코드는 현재 사용자 이름, 호스트 이름, 현재 작업 디렉토리 등을 색상과 함께 표시하는 프롬프트를 생성합니다. 여기서 `%F{color}`는 텍스트 색상을 지정하고, `%~`는 현재 작업 디렉토리 경로를 나타냅니다. `%(?..)`는 이전 명령어의 종료 상태에 따라 다른 내용을 표시하는 조건부 표현식입니다.

oh-my-zsh 테마 파일은 이러한 `PS1` 설정을 포함하는 스크립트입니다. 새로운 테마를 만들려면, `.zshrc` 파일에 다음과 같은 내용을 추가하여 새로운 테마 파일을 지정할 수 있습니다.

ZSH_THEME="my_custom_theme"

그리고 `~/.oh-my-zsh/themes/my_custom_theme.zsh-theme` 파일을 생성하여 원하는 프롬프트 코드를 작성합니다. 예를 들어, 간단한 사용자 정의 테마는 다음과 같이 작성할 수 있습니다.

# ~/.oh-my-zsh/themes/my_custom_theme.zsh-theme

# 사용자 정의 테마: 사용자 이름 @ 호스트 이름: 현재 경로 $
PROMPT='%F{yellow}%n@%F{cyan}%m %F{blue}%~%f $ '
RPROMPT='' # 오른쪽 프롬프트 비활성화

이 코드는 현재 사용자 이름과 호스트 이름을 노란색과 청록색으로, 현재 작업 디렉토리를 파란색으로 표시하고, 마지막에 '$ ' 기호를 붙이는 간단한 프롬프트를 생성합니다. `RPROMPT`는 터미널 오른쪽 끝에 표시되는 프롬프트로, 여기서는 비워두어 비활성화했습니다. 이처럼 zsh의 다양한 기능을 활용하면 매우 복잡하고 정보 밀도가 높은 프롬프트를 만들 수 있습니다.

실용 팁: 기존의 인기 있는 테마 파일들을 `~/.oh-my-zsh/themes/` 디렉토리에서 열어보고, 어떤 방식으로 프롬프트가 구성되는지 살펴보는 것이 좋습니다. 예를 들어, `git` 정보를 표시하는 `git_prompt_info`와 같은 함수를 어떻게 사용하는지 배우면, 자신의 테마에 Git 브랜치 이름이나 커밋 상태 등을 표시하는 기능을 추가할 수 있습니다. M2 맥북에서도 이러한 커스터마이징은 3초 안에 적용 가능합니다.