tmux configuration

tmux config file의 위치, option scope, key binding, format과 안전한 reload 방법.

Summary

tmux server가 시작될 때 config file을 읽는다.
config는 shell script가 아니라 tmux command를 한 줄씩 기록하는 file이다.
server, session, window, pane option의 scope를 구분하고 global 변경에는 -g를 명시한다.
기존 server에는 source-file로 다시 읽되, 적용 전에 별도 server에서 syntax를 검증한다.

File Locations

~/.tmux.conf: 전통적인 user config
$XDG_CONFIG_HOME/tmux/tmux.conf: XDG user config
/etc/tmux.conf: 일반적인 system-wide config 위치이며 build 또는 platform에 따라 다를 수 있다.
tmux -f PATH: 지정한 config file로 새 server를 시작한다.

정확한 검색 순서와 system config path는 설치된 version의 man 1 tmux를 확인한다. 이미 실행 중인 server는 새 client를 열기만 해서는 config를 자동으로 다시 읽지 않는다.

Syntax

# comment
set-option -g mouse on
set-window-option -g mode-keys vi
bind-key r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"

command는 한 줄에 하나씩 쓴다.
공백이 있는 argument는 single quote, double quote 또는 backslash로 quote한다.
#로 시작하는 줄은 comment다.
여러 command를 연결할 때는 semicolon을 tmux parser에 전달하도록 escape해야 할 수 있다.
tmux config는 shell과 비슷한 quoting 일부를 지원하지만 shell의 $() 같은 command substitution을 직접 실행하는 script가 아니다.

Options

Scope

server option: tmux server 전체에 적용한다. 예: buffer-limit.
session option: 특정 session 또는 -g를 사용한 global default에 적용한다. 예: status, mouse.
window option: 특정 window 또는 global window default에 적용한다. 예: mode-keys, automatic-rename.
pane option: pane에 적용한다.
user option: @name 형식이며 plugin이나 user config에서 자유롭게 사용한다.

# 현재 server option
tmux show-options -s
 
# global session option
tmux show-options -g
 
# global window option
tmux show-window-options -g

Practical Defaults

# mouse로 pane 선택, resize, copy mode 사용
set-option -g mouse on
 
# scrollback line 수
set-option -g history-limit 50000
 
# window와 pane index를 1부터 시작
set-option -g base-index 1
set-window-option -g pane-base-index 1
 
# vi-style copy mode
set-window-option -g mode-keys vi
 
# terminal capability는 실제 terminal과 tmux version에 맞춰 조정
set-option -g default-terminal "tmux-256color"

default-terminal을 무조건 바꾸면 terminfo가 없는 remote host나 오래된 system에서 application 표시가 깨질 수 있다. 먼저 infocmp tmux-256color로 entry가 있는지 확인한다.

Key Bindings

# prefix table: prefix 다음 r
bind-key r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded"
 
# prefix 없이 Alt+h/j/k/l로 pane 이동
bind-key -n M-h select-pane -L
bind-key -n M-j select-pane -D
bind-key -n M-k select-pane -U
bind-key -n M-l select-pane -R

bind-key는 기본적으로 prefix key table에 binding을 만든다.
-n은 -T root의 shorthand이며 prefix 없이 key를 처리한다.
unbind-key KEY는 binding을 제거한다.
tmux list-keys -T prefix와 tmux list-keys -T root로 충돌을 확인한다.

Formats

tmux format은 #{name} 문법으로 session, window, pane 상태를 command output과 status line에 삽입한다.

set-option -g status-left '#S '
set-option -g status-right '#{?client_prefix,PREFIX ,}%Y-%m-%d %H:%M'

tmux display-message -p '#{session_name}:#{window_index}.#{pane_index}'
tmux list-panes -a -F '#{pane_id} #{pane_current_command} #{pane_current_path}'

Reload and Validation

# 현재 server에 적용
tmux source-file ~/.tmux.conf
 
# 별도 socket 이름으로 isolated server에서 config 확인
tmux -L config-test -f ~/.tmux.conf new-session -d -s config-test
tmux -L config-test list-sessions
tmux -L config-test kill-server

별도 socket을 사용하면 현재 작업 중인 기본 tmux server에 영향을 주지 않고 config를 확인할 수 있다. 검증용 server만 대상으로 kill-server를 실행한다.

Troubleshooting

reload 후 변경이 없으면 option scope와 target을 확인한다. 기존 session에는 global default 변경이 즉시 반영되지 않는 option도 있다.
unknown option 또는 unknown command는 설치된 tmux가 config 문법보다 오래된 경우가 많다. tmux -V와 manual을 확인한다.
key가 동작하지 않으면 tmux list-keys로 실제 table과 중복 binding을 확인한다.
color가 깨지면 바깥 terminal의 TERM, tmux의 default-terminal, host의 terminfo를 함께 확인한다.
config가 server 시작을 막으면 tmux -f /dev/null 또는 별도 최소 config로 원인을 격리한다.

History

codex:: 2026-07-27 Added config locations, syntax, option scope, key bindings, formats, isolated validation, and troubleshooting guidance.

config

목차