에디터 환경을 Neovim + LazyVim 조합으로 구성해 보기로 했다.
LazyVim은 설정 파일을 직접 짜지 않아도 플러그인과 키맵이 잘 갖춰진 상태로 시작할 수 있다는 점이 가장 큰 장점이다. 설치도 명령어 몇 줄이면 끝난다고 해서 가볍게 시작했다.
그런데 첫 화면부터 물음표 박스가 나를 반겼다.
brew install은 뜻밖의 에러를 뱉었고, 한글 입력 상태에서는 노멀 모드 명령이 먹지 않았다. 설치 자체는 쉬웠지만 그 이후가 만만치 않았던 셈이다.
이번 글은 macOS에서 Neovim + LazyVim을 설치하는 과정과, 그 과정에서 마주친 오류와 해결 방법을 기록으로 남긴 것이다.
나처럼 Mac에서 LazyVim을 처음 세팅하는 누군가에게 도움이 되었으면 좋겠다.
0. 설치 환경
| 구분 | 내용 |
|---|---|
| 기기 | Mac mini (Apple Silicon) |
| OS | macOS |
| 패키지 매니저 | Homebrew |
| 에디터 | Neovim + LazyVim (starter) |
| 폰트 | JetBrainsMono Nerd Font |
1. 필요한 도구 설치
LazyVim을 쓰려면 Neovim 외에도 몇 가지 도구가 필요하다. Homebrew로 한 번에 설치한다.
brew install neovim git ripgrep fd lazygit node각 도구의 역할은 다음과 같다.
- neovim: 에디터 본체. Homebrew는 항상 최신 안정 버전을 설치해 준다.
- git: LazyVim 설치와 플러그인 관리에 사용된다.
- ripgrep, fd: 파일 검색과 텍스트 검색 속도를 책임진다.
- lazygit: 터미널 안에서 쓰는 Git UI다. LazyVim에서 바로 호출할 수 있다.
- node: 필수는 아니지만 LSP 서버 설치(Mason) 과정에서 필요한 경우가 많아 같이 설치했다.
treesitter 파서를 빌드하려면 C 컴파일러도 필요하다. Xcode Command Line Tools가 없다면 설치한다.
xcode-select --install이미 설치되어 있다면 “command line tools are already installed”라는 메시지가 나오므로 넘어가면 된다.
설치가 끝나면 버전을 확인한다.
nvim --version2. Nerd Font 설치
LazyVim은 파일 탐색기, 상태바, 메뉴 곳곳에 아이콘을 사용한다. 이 아이콘을 표시하려면 Nerd Font가 필요하다.
brew install --cask font-jetbrains-mono-nerd-font여기서 중요한 점이 하나 있다.
폰트를 설치하는 것과 터미널이 그 폰트를 쓰는 것은 별개다.
이 부분은 아래 삽질 파트에서 자세히 다룬다.
3. LazyVim 설치
LazyVim은 공식 starter 템플릿을 클론하는 방식으로 설치한다.
먼저 기존 Neovim 설정이 있다면 백업한다. (처음 설치라면 아무 일도 일어나지 않으니 그냥 실행해도 된다.)
mv ~/.config/nvim ~/.config/nvim.bak 2>/dev/null
mv ~/.local/share/nvim ~/.local/share/nvim.bak 2>/dev/null
mv ~/.local/state/nvim ~/.local/state/nvim.bak 2>/dev/null
mv ~/.cache/nvim ~/.cache/nvim.bak 2>/dev/null그리고 starter를 클론한다.
git clone https://github.com/LazyVim/starter ~/.config/nvim
rm -rf ~/.config/nvim/.git.git 폴더를 지우는 이유는, 나중에 내 설정을 내 저장소에 올릴 수 있도록 starter의 Git 연결을 끊어두기 위해서다.
이제 Neovim을 실행한다.
nvim첫 실행에서는 lazy.nvim이 플러그인을 자동으로 설치한다. 설치가 끝나면 아래 명령어로 상태를 점검한다.
:LazyHealth모든 플러그인을 로드해 보고 문제가 없는지 확인해 주는 명령어다. 공식 문서에서도 설치 후 실행을 권장한다.
그리고 드디어 LazyVim 대시보드가 떴다.
…그런데 뭔가 이상했다.
4. 삽질 1: 아이콘이 전부 물음표로 깨진다
(여기에 깨진 대시보드 스크린샷 삽입)
메뉴마다 붙어 있는 저 물음표 박스는 무엇인가
Find File, New File, Projects 옆에 아이콘이 있어야 할 자리에 전부 ? 박스가 표시됐다.
원인
터미널이 Nerd Font를 사용하고 있지 않았기 때문이다.
앞에서 brew install --cask font-jetbrains-mono-nerd-font로 폰트는 설치했지만, 폰트가 시스템에 설치된 것과 터미널 앱이 그 폰트를 사용하도록 설정된 것은 전혀 다른 이야기다. 터미널은 여전히 기본 폰트를 쓰고 있었고, 기본 폰트에는 아이콘 글리프가 없으니 물음표로 표시된 것이다.
해결
터미널 앱의 설정에서 폰트를 직접 지정해야 한다.
- Terminal.app: 설정 → 프로파일 → 텍스트 → 서체 “변경” →
JetBrainsMono Nerd Font - iTerm2: Settings → Profiles → Text → Font →
JetBrainsMono Nerd Font - Ghostty:
~/.config/ghostty/config에 아래 줄 추가
font-family = "JetBrainsMono Nerd Font"설정을 바꿨다면 터미널을 완전히 종료했다가 다시 실행해야 확실하게 적용된다. 폰트 목록에 JetBrainsMono가 여러 변형으로 보인다면 이름 뒤에 Nerd Font가 붙은 항목을 고르면 된다.
다시 nvim을 열어 보니 아이콘이 제대로 표시됐다.
5. 한글 입력 문제: 노멀 모드에서 명령이 안 먹힌다
Vim 계열 에디터를 한글 사용자가 쓸 때 가장 큰 불편함이다.
Vim은 h, j, k, l, dd, yy 같은 키 입력으로 동작한다. 그런데 입력 소스가 한글 상태에서 ESC를 눌러 노멀 모드로 돌아오면 ㅗ, ㅓ, ㅏ, ㅣ가 입력되어 명령이 먹히지 않는다.
그래서 Insert 모드를 빠져나올 때 자동으로 영문 입력 소스로 전환해 주는 도구를 사용한다. macOS에서는 im-select가 대표적이다.
6. 삽질 2: im-select 설치가 막힌다
공식 안내대로 tap을 추가하고 설치를 시도했다.
brew tap daipeihust/tap
brew install im-select그런데 설치 단계에서 에러가 발생했다.
(여기에 brew 에러 스크린샷 삽입)
Error: Refusing to load formula daipeihust/tap/im-select from untrusted tap daipeihust/tap.
Run `brew trust --formula daipeihust/tap/im-select` or `brew trust daipeihust/tap` to trust it.그리고 im-select를 실행하면 당연하게도 command not found가 출력됐다.
원인
최근 Homebrew는 신뢰하지 않는 서드파티 tap의 formula를 기본적으로 로드하지 않는다. tap을 추가(brew tap)하는 것만으로는 부족하고, 사용자가 해당 tap을 신뢰한다고 명시적으로 등록해야 한다.
에러 메시지에 해결 방법이 그대로 적혀 있었다.
해결
brew trust daipeihust/tap
brew install im-select특정 formula만 신뢰하고 싶다면 에러 메시지에 나온 형태 그대로 실행하면 된다.
brew trust --formula daipeihust/tap/im-select서드파티 tap을 신뢰한다는 것은 해당 tap의 코드를 내 컴퓨터에서 실행하겠다는 뜻이다. 출처를 확인하고 신뢰할 수 있는 경우에만 등록하자.
설치가 끝나면 현재 입력 소스 ID를 확인한다.
im-select영문 자판이라면 보통 아래와 같이 출력된다.
com.apple.keylayout.ABC7. LazyVim에 한글 자동 전환 적용하기
이제 Neovim에서 im-select를 사용하도록 플러그인을 추가한다. LazyVim은 lua/plugins/ 폴더 안에 파일을 만들면 자동으로 읽어 들인다.
~/.config/nvim/lua/plugins/im-select.lua 파일을 생성한다.
return {
"keaising/im-select.nvim",
event = "VeryLazy",
opts = {
default_im_select = "com.apple.keylayout.ABC",
default_command = "im-select",
set_default_events = { "InsertLeave", "CmdlineLeave" },
set_previous_events = { "InsertEnter" },
},
}각 옵션의 의미는 다음과 같다.
default_im_select: 노멀 모드에서 사용할 기본 입력 소스. 앞에서im-select로 확인한 ID를 넣는다.set_default_events: Insert 모드나 명령줄 모드를 빠져나올 때 기본 입력 소스(영문)로 전환한다.set_previous_events: Insert 모드에 다시 진입하면 이전에 쓰던 입력 소스(한글)로 복원한다.
영문 입력 소스 ID가 ABC가 아니라 U.S. 등으로 출력된다면 default_im_select 값을 출력된 ID 그대로 바꿔야 한다.
파일을 저장하고 Neovim을 재시작하면 플러그인이 설치된다. 이제 한글로 글을 쓰다가 ESC를 눌러도 영문으로 자동 전환되어, 입력 소스를 매번 수동으로 바꿀 필요가 없다.
8. 설치 후 이것부터 해보자
LazyVim은 <Space> 키가 리더 키다. <Space>를 누르고 잠시 기다리면 which-key가 사용 가능한 키맵을 보여주니, 처음에는 이것만으로도 충분히 탐색할 수 있다.
| 키 | 기능 |
|---|---|
<Space> | 키맵 도움말(which-key) |
<Space>e | 파일 탐색기 |
<Space><Space> | 파일 검색 |
<Space>/ | 프로젝트 전체 텍스트 검색 |
<Space>gg | lazygit 실행 |
그리고 아래 두 명령어도 알아두면 좋다.
:Mason: LSP 서버, 포매터, 린터를 설치하고 관리하는 화면:LazyExtras: 언어별 추가 기능(TypeScript, Python, Java 등)을 켜고 끄는 화면
개발하는 언어에 맞는 extras를 켜면 LSP, 포매터, 디버거 설정이 한 번에 갖춰진다.
참고: :LazyHealth에서 경고가 뜬다면
:LazyHealth를 실행했을 때 tree-sitter 관련 경고가 표시될 수 있다. LazyVim은 tree-sitter CLI를 요구사항으로 안내하고 있으므로, 경고가 보인다면 아래와 같이 설치하고 다시 확인해 보자.
brew install tree-sitter-cli마치며
설치 명령어만 보면 brew install과 git clone이 전부였다.
하지만 실제로 쓸 수 있는 환경이 되기까지는 Nerd Font 적용, Homebrew의 tap 신뢰 설정, 한글 입력 소스 전환이라는 세 가지 관문이 더 있었다. 하나같이 공식 문서를 한 번만 꼼꼼히 읽었다면 피할 수 있었을 일이지만, 직접 부딪혀 보니 원인이 훨씬 확실하게 이해됐다.
특히 아이콘 깨짐은 “폰트를 설치했는데 왜 안 되지?”에서 시작해서, 설치와 적용은 다른 문제라는 사실로 끝났다. 이런 문제는 증상만 검색하면 해결책이 너무 많아서 오히려 헷갈리기 쉬운데, 결국 원인을 먼저 파악하는 쪽이 빨랐다.
이제 환경은 갖춰졌으니 앞으로 LazyVim을 쓰면서 알게 되는 것들도 하나씩 기록해 볼 생각이다.
이 글이 Mac에서 Neovim과 LazyVim을 시작하려는 누군가에게 도움이 되었으면 좋겠다.
P.S. 에디터 설정은 한 번 끝내는 것이 아니라, 쓰면서 계속 고쳐 나가는 것 같다.