[WezTerm] 터미널과 tmux를 Lua 파일 하나로

개발자 도구 · 터미널 & 환경

[WezTerm] 터미널과 tmux를 Lua 파일 하나로

WezTerm은 터미널 에뮬레이터에 멀티플렉서(탭·분할·세션 유지)를 같이 넣은 오픈소스 터미널이에요. 설정은 전부 Lua 파일 하나로 해요. 같은 파일이 macOS·Linux·Windows에서 그대로 돌아가요. 설치와 첫 설정, 리더 키, 원격 멀티플렉싱, 그리고 쓰기 전에 알아둘 함정까지 공식 문서 기준으로 정리했어요.

터미널 앱과 tmux를 따로 설정하던 자리를 합치는 도구예요

보통 개발 환경은 두 겹이에요. 창을 그리는 터미널 앱(iTerm2, Terminal.app 등)이 있어요. 그 안에서 tmux 같은 멀티플렉서가 탭·분할·세션을 맡아요. 설정 파일도 두 개, 단축키 체계도 두 개가 돼요.

WezTerm은 이 두 역할을 한 프로그램에 넣었어요. 공식 기능 목록에 "로컬과 원격 호스트에서의 네이티브 pane·tab·window 멀티플렉싱"이 첫 줄로 올라가 있어요. 분할 창과 탭이 터미널 자체 기능이라 마우스로 크기를 조절하고 스크롤백도 그대로 써요.

또 하나의 축은 설정 방식이에요. 옵션을 GUI 체크박스가 아니라 Lua 코드로 적어요. dotfiles 저장소에 파일 하나만 넣어두면 회사 맥, 집 리눅스, 윈도우 PC가 같은 설정을 가져가요. 공식 문서 기준 지원 플랫폼은 Linux, macOS, Windows 10, FreeBSD, NetBSD예요.

구분	터미널 앱 + tmux	WezTerm
설정 파일	앱 설정(GUI) + .tmux.conf	wezterm.lua 하나
분할·탭	tmux가 텍스트로 그림	터미널이 네이티브로 그림
원격 세션 유지	원격 서버에서 tmux 실행	SSH·TLS·Unix 도메인 멀티플렉싱
플랫폼	앱마다 다름	macOS·Linux·Windows·BSD 공통
확장	셸 스크립트·플러그인	Lua 이벤트 훅

설치는 cask 한 줄, 설정은 Lua 파일 하나로 시작해요

설치와 CLI 경로

macOS에서는 Homebrew cask가 가장 간단해요. 공식 설치 문서가 안내하는 명령은 아래와 같아요. Big Sur 이상을 지원해요. 유니버설 바이너리라 Apple Silicon과 Intel 모두 같은 파일을 써요.

# 안정판
brew install --cask wezterm

# 나이틀리(최신 개발판)
brew install --cask wezterm@nightly
brew upgrade --cask wezterm@nightly --greedy-latest

# ~/.zshrc — wezterm CLI를 셸에서 쓰려면
PATH="$PATH:/Applications/WezTerm.app/Contents/MacOS"
export PATH

앱만 설치하면 셸에서 wezterm 명령이 잡히지 않아요. 뒤에 나오는 wezterm connect, wezterm show-keys 같은 CLI를 쓰려면 위처럼 앱 번들 안의 경로를 PATH에 추가해야 해요. GitHub 릴리스의 ZIP을 받아 Applications로 옮기는 방법과 MacPorts 설치도 문서에 있어요.

설정 파일 위치와 자동 리로드

WezTerm은 설정 파일을 몇 군데서 순서대로 찾아요. 가장 우선은 --config-file 인자, 그다음 WEZTERM_CONFIG_FILE 환경변수, 그 뒤로 XDG 경로와 $HOME/.config/wezterm/wezterm.lua가 있어요. 문서가 권하는 기본 위치는 홈 디렉터리의 .wezterm.lua예요.

처음 파일은 공식 예제를 그대로 가져오면 돼요. config_builder()는 빈 테이블 대신 기본값이 잡힌 설정 객체를 만들어줘서 더 안전한 출발점이라고 문서가 설명해요.

-- ~/.wezterm.lua
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.initial_cols = 120
config.initial_rows = 28
config.font_size = 10
config.color_scheme = 'AdventureTime'

return config

저장하면 따로 재시작할 필요가 없어요. WezTerm이 불러온 설정 파일을 감시하다가 바뀌면 자동으로 다시 읽어요. 대부분의 옵션이 바로 적용돼요. 강제로 다시 읽고 싶으면 CTRL+SHIFT+R을 누르면 돼요.

tmux식 조작은 리더 키로 옮겨요

tmux의 prefix 키에 익숙하다면 WezTerm의 leader가 같은 역할이에요. 리더 키를 누르면 정해진 시간 동안 모달 상태가 돼요. 그 안에서 누른 키가 LEADER 수식어와 묶여요.

아래는 공식 문서 예제예요. Ctrl-A를 리더로 잡고 1초 안에 | 를 누르면 좌우 분할이 돼요. 두 번째 바인딩은 리더 상태에서 Ctrl-A를 한 번 더 누르면 셸에 원래의 Ctrl-A를 보내도록 한 것이에요.

config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }
config.keys = {
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  {
    key = 'a',
    mods = 'LEADER|CTRL',
    action = wezterm.action.SendKey { key = 'a', mods = 'CTRL' },
  },
}

수식어는 CMD(SUPER), CTRL, SHIFT, ALT(OPT), LEADER를 써요. 여러 개는 "CMD|CTRL"처럼 | 로 이어요. 기본 단축키 중 겹치는 건 DisableDefaultAssignment로 끌 수 있어요. 지금 적용된 전체 바인딩은 wezterm show-keys로 확인해요.

tmux 없이 세션을 유지하는 건 도메인이 맡아요

멀티플렉싱의 단위를 WezTerm은 도메인이라고 불러요. 공식 문서가 설명하는 도메인은 세 종류예요.

Unix 도메인 — 로컬 세션 유지

소켓 파일로 붙는 로컬 멀티플렉서예요. 아래처럼 설정하고 default_gui_startup_args로 시작할 때 자동 연결하면 GUI 창을 닫았다 열어도 안의 탭과 분할이 그대로 남아요. 수동으로는 wezterm connect unix로 붙어요.

config.unix_domains = {
  { name = 'unix' },
}
config.default_gui_startup_args = { 'connect', 'unix' }

SSH 도메인 — 원격 서버 세션

ssh_domains에 서버를 등록하고 wezterm connect 이름으로 붙어요. 원격 쪽 탭·분할이 로컬 창에 네이티브로 그려져요. 20230408 버전부터는 ~/.ssh/config의 호스트가 자동으로 등록돼요. 멀티플렉싱 연결은 SSHMUX: 접두어로 구분돼요. 단, 원격 서버에도 wezterm이 설치돼 있어야 해요.

TLS 도메인 — 암호화 TCP 연결

처음 인증서 교환은 SSH로 하고 이후에는 TLS로 붙는 방식이에요. 인증서 관리와 끊긴 뒤 재접속을 WezTerm이 처리한다고 문서에 나와 있어요.

마우스 없이 복사하는 모드가 두 개 있어요

Quick Select(기본 CTRL-SHIFT-SPACE)는 화면에서 URL, 경로, git 해시, IP, 숫자를 찾아 한두 글자 라벨을 붙여요. 라벨을 치면 복사돼요. 대문자로 치면 복사한 뒤 바로 붙여넣기까지 해요. 로그에서 커밋 해시를 뽑을 때 유용한 기능이에요. 찾는 패턴은 quick_select_patterns로 추가해요.

Copy Mode(기본 CTRL-SHIFT-X)는 vim 방식으로 스크롤백을 움직여요. h/j/k/l로 이동하고 v로 선택을 시작해 y로 복사하면서 빠져나와요. Esc나 q를 누르면 그냥 나가요.

그 밖에 리가처와 컬러 이모지, 폰트 폴백, iTerm2 이미지 프로토콜과 Kitty 그래픽 지원, 시리얼 포트 연결 같은 기능도 공식 기능 목록에 올라가 있어요.

쓰기 전에 알아둘 함정이 있어요

• 안정판 릴리스 간격이 길어요. GitHub 릴리스 페이지의 최신 안정 태그는 20240203-110809-5046fc22예요. 최근 수정이 필요하면 나이틀리를 설치해야 해요.
• 설정 파일은 프로세스마다 여러 번 평가될 수 있어요. 문서는 시작과 리로드 때 반복 실행되니 백그라운드 프로세스를 무조건 띄우는 식의 부작용 코드를 넣지 말라고 경고해요.
• 리더 키로 Ctrl-A를 잡으면 셸의 줄 처음 이동과 겹쳐요. 위 예제처럼 SendKey 바인딩을 같이 넣어야 원래 동작을 쓸 수 있어요.
• SSH 도메인 멀티플렉싱은 원격에도 wezterm이 있어야 해요. 설치할 수 없는 서버라면 일반 SSH 접속이나 원격 tmux를 그대로 써야 해요.
• update-right-status 이벤트는 폐기 예정(deprecated)이에요. 상태바를 꾸미는 예제를 옮겨올 때는 update-status로 바꿔 써야 해요.

여러 OS를 오가며 dotfiles로 관리하는 사람에게 맞아요

맥과 리눅스, 윈도우를 번갈아 쓰면서 터미널 설정을 한 곳에서 관리하고 싶은 경우에 잘 맞아요. tmux를 주로 로컬 분할용으로만 쓰고 있었다면 Unix 도메인으로 그 역할을 옮겨도 돼요.

반대로 설정 코드를 만지기 싫고 GUI에서 몇 번 클릭해 끝내고 싶다면 Lua 파일 관리가 부담일 수 있어요. 원격 서버에서 tmux 세션을 오래 붙잡아 두는 작업 방식이라면 기존 조합을 유지하는 편이 단순해요.

시작은 위 최소 예제 파일을 만들고 color_scheme과 폰트만 바꿔 저장해 보는 것부터예요. 자동 리로드가 되는 걸 확인한 다음 리더 키와 분할 바인딩을 하나씩 추가하면 돼요.

설정 팁 기존에 쓰던 기본 단축키가 무엇인지 모를 때는 wezterm show-keys 출력을 먼저 보고 겹치는 키만 DisableDefaultAssignment로 끈 뒤 새 바인딩을 넣는 순서가 안전해요.

출처

WezTerm 공식 문서 — Configuration Files WezTerm 공식 문서 — Key Binding WezTerm 공식 문서 — Multiplexing WezTerm 공식 문서 — macOS 설치 GitHub — wezterm/wezterm Releases

이 글은 직접 사용기가 아니라 WezTerm 공식 문서와 릴리스 페이지를 기준으로 정리한 객관 소개예요. 버전에 따라 기본 단축키와 옵션이 달라질 수 있으니 설치한 버전의 문서를 함께 확인하세요.