tmux configuration

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

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

• ~/.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를 시작한다.

# 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가 아니다.

• 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

# 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"

# 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로 충돌을 확인한다.

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}'

# 현재 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

• 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로 원인을 격리한다.

• tmux
• tmux cheatsheet
• Configuring tmux
• tmux(1) manual

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