Skip to content
Search

Tmux

lastmod 2026-04-27created 2015-09-0864 edits

Tmux is a software application that can be used to multiplex several virtual consoles, allowing a user to access multiple separate terminal sessions inside a single terminal window or remote terminal session. It is useful for handling multiple programs from a command-line interface and for detaching programs from a Unix shell. It provides much of the same functionality as GNU Screen, but is distributed under a BSD license.

Categories

Plugins

ETC

Keymaps

All of the commands below are entered after the prefix. The default prefix is <CTRL-B>.

A : before a command moves to the prompt.

Windows (tabs)

  • c - new window
  • , - name window
  • w - list windows
  • f - find window
  • & - kill window
  • . - move window - prompted for a new number
  • :movew<CR> - move window to the next unused number
  • {화살표} (arrow keys) - move between windows
  • c - create one more window set
  • {0~9} - move to window (check the numbers at the bottom)

Panes (splits)

  • % - split pane into columns
  • " - split pane into rows
  • o - swap panes
  • q - show pane numbers
  • x - kill pane
  • Alt+2 - make sizes equal (equal columns)
  • Alt+1 - make sizes equal (equal rows)
  • {space} - Toggle between layouts
  • <Ctrl-o> - rotate pane order (counterclockwise)
  • <Alt-o> - rotate pane order (clockwise)

ETC

  • z: Toggle Fullscreen
  • d - Detach
  • t - show the current time in huge digits

Commands

  • tmux new-session -s SESSION_NAME - create a new session with a session name
    • Same as tmux new -s SESSION_NAME
  • tmux list-sessions - shows the list of currently open sessions.
    • Same as tmux ls
  • tmux attach-session -t TARGET_SESSION - enters the session named TARGET_SESSION.
    • Same as tmux a -t SESSION_NAME
  • tmux kill-session -t SESSION_NAME - remove SESSION_NAME
  • tmux has-session -t TARGET_SESSION - checks whether a session named TARGET_SESSION is open.

How to specify the configuration file

  • /etc/tmux.conf - location of the system-wide configuration file (applies to all users)
  • ~/.tmux.conf - location of the per-user configuration file
  • TMUX_CONF=~/custom/tmux.conf - using an environment variable.
  • tmux -f /path/to/custom-tmux.conf - specifying it on the command line.

Environment variables

TMUX
A variable set while a tmux session is running.
Contains the socket path and PID of the current tmux session, and is set when running inside tmux.
Setting it directly from outside a session is not typical.
TMUX_CONF
Used to customize the tmux configuration file path.
If you want to use a specific configuration file, you can set this variable so that tmux loads the specified file when it starts.
Default setting: export TMUX_CONF=/path/to/your/tmux.conf
TMUX_PLUGIN_MANAGER_PATH
A variable that specifies the plugin installation location when using tpm (tmux plugin manager).
Default path: ~/.tmux/plugins (the default is used if not set separately)
TMUX_TMPDIR
A variable that sets the directory where tmux stores temporary files.
Useful when you want to specify a different temporary directory instead of the system default /tmp.
TERM
Specifies the terminal emulation and is an important variable in tmux. It should usually be set to xterm-256color or screen-256color.
Example: export TERM=xterm-256color
PATH
When tmux runs, the PATH environment variable must be set correctly for tmux to find the external programs it needs.
This path can differ between root and regular users in particular, so it is a good idea to check that tmux is correctly included in the path.
LC_CTYPE, LC_ALL, LANG
Locale variables for supporting character encodings such as UTF-8 in tmux.
A correct locale setting (such as en_US.UTF-8) must be specified for special characters and Unicode to display properly in tmux.

Log files

tmux does not create log files automatically by default, so to save logs you can start a session with the following command. 

tmux new-session -f ~/.tmux.conf 2> ~/tmux.log

To record the output of a specific command to a file within a tmux session, you can use the following command: 

tmux pipe-pane -o 'cat > ~/tmux_output.log'

Checking the tmux server log: 

tmux -vvvv new-session

Creates files of the form tmux-server-*.log in /tmp.

You can also enable logging by adding log settings to the .tmux.conf file. 

set-option -g status on
set-option -g message-command-style bg=yellow,fg=black
set-option -g terminal-overrides 'xterm*:smcup@:rmcup@'

After this, restarting tmux and checking the logs and command styles makes errors a bit easier to track down.

You can use these methods to record logs related to tmux sessions and configuration and use them for troubleshooting.

Truecolor

For terminal settings, see Terminal emulator#Truecolor. 

# 256 color mode.
set -g default-terminal "screen-256color"

# TrueColor/RGB capability set
set -sa terminal-overrides ",xterm-256color:RGB"

Reloading tmux config

If you have made changes to your tmux configuration file in the ~/.tmux.conf file, it shouldn’t be necessary to start the server up again from scratch with kill-server. Instead, you can prompt the current tmux session to reload the configuration with the source-file command.

This can be done either from within tmux, by pressing Ctrl+B and then : to bring up a command prompt, and typing: 

:source-file ~/.tmux.conf

Or simply from a shell: 

$ tmux source-file ~/.tmux.conf

This should apply your changes to the running tmux server without affecting the sessions or windows within them.

Focus Event 

set -g focus-events on

This event is needed for things like FocusGained / FocusLost autocmds to work. For example:

  • Automatically reloading files when you come back from another window (:checktime)
  • Auto-saving when focus is lost
  • Detecting external changes in plugins such as lazygit and neogit
  • Using focus state in some copilot or LSP features

Change prefix key

To change it to C-s, add the following to the ~/.tmux.conf file. 

set -g prefix C-s
unbind C-b

# 현재, 터미널에 실행중인 프로그램에 prefix 키를 전송한다.
bind C-s send-prefix

Session 

# 새로운 Session 만들기 - session 이름은 설정하지 않고 (0,1,2,.. 순서로 생성)
tmux

# 새로운 Session 만들기 - session 이름 = (session_name)
tmux new -s (session_name)

# Session name 수정
ctrl + b, $
# 원하는 이름 적고 Enter

# Session 종료 - session 사라짐
exit or ctrl + d # 주의! window나 pane이 열려있을 때는 pane -> window 순으로 하나씩 닫힘

# Session 닫기(detach) - 백그라운드에서 계속 돌아감(server 접속이 끊겨도 계속 돌아감)
# 매우 유용하게 사용할 수 있습니다 - tmux의 엄청 큰 장점
ctrl + b, d

# Session 목록 확인
tmux ls

# Detached session 다시 열기(attach)
tmux at -t (session_name)
# (session_name)은 tmux ls로 확인

Tmux open new pane in same directory

To keep the current directory when opening a new window, use -c "#{pane_current_path}": 

# Set the control character to Ctrl+Spacebar (instead of Ctrl+B)
set -g prefix C-space
unbind-key C-b
bind-key C-space send-prefix

# Set new panes to open in current directory
bind c new-window -c "#{pane_current_path}"
bind '"' split-window -c "#{pane_current_path}"
bind % split-window -h -c "#{pane_current_path}"

Mouse mode 

## 2.1 이상 버전
set -g mouse on

## 2.1 아래 버전
set -g mode-mouse on

## UTF-8 문자열 선택 여부 (최신버전에서 작동하지 않는듯?)
set -g mouse-utf8 on

If you use iTerm2, you need to enable the setting below. 

Profiles -> Terminal -> Save lines to scrollback when an app status bar is present

Setting environment variables

In the config file: 

set-environment -g MY_VARIABLE value

Displaying messages 

tmux display-message [-aINpv] [-c target-client] [-d delay] [-F format] [-t target-pane] [message]

Commonly used format strings

  • #S - session name
  • #I - window number
  • #P - pane number
  • #W - window name
  • #T - PC name
  • #{window_width} - window width
  • #{window_height} - window height

System Clipboard

tmux logging 

$ tmux capture-pane -pS -1000000 > tmux.log

Clear history 

$ tmux clear-history

Session

Starting a Tmux Session: 

tmux new-session -s <session-name>

Connecting to existing session: 

tmux attach -t <session-name>

neovim compatibility 

  - OK: escape-time: 0ms
  - INFO: $TERM: screen
  - ERROR: $TERM should be "screen-256color" or "tmux-256color" in tmux. Colors might look wrong.
    - ADVICE:
      - Set default-terminal in ~/.tmux.conf:
          set-option -g default-terminal "screen-256color"
      - https://github.com/neovim/neovim/wiki/FAQ
  - WARNING: Neither Tc nor RGB capability set. True colors are disabled. |'termguicolors'| won't work properly.
    - ADVICE:
      - Put this in your ~/.tmux.conf and replace XXX by your $TERM outside of tmux:
          set-option -sa terminal-overrides ',XXX:RGB'
      - For older tmux versions use this instead:
          set-option -ga terminal-overrides ',XXX:Tc'

Saving logs (history) 

bind-key P command-prompt -p 'save history to filename:' -I '~/tmux.history' 'capture-pane -S -32768 ; save-buffer %1 ; delete-buffer'

-> Not tested yet. Try it later.

set vs set-option

They are the same. set is just an alias of set-option.

tmux-session

A simple way to handle it with a bash script: 

#!/usr/bin/env bash
# Save and restore the state of tmux sessions and windows.
# TODO: persist and restore the state & position of panes.
set -e

dump() {
  local d=$'\t'
  tmux list-windows -a -F "#S${d}#W${d}#{pane_current_path}"
}

save() {
  dump > ~/.tmux-session
}

terminal_size() {
  stty size 2>/dev/null | awk '{ printf "-x%d -y%d", $2, $1 }'
}

session_exists() {
  tmux has-session -t "$1" 2>/dev/null
}

add_window() {
  tmux new-window -d -t "$1:" -n "$2" -c "$3"
}

new_session() {
  cd "$3" &&
  tmux new-session -d -s "$1" -n "$2" $4
}

restore() {
  tmux start-server
  local count=0
  local dimensions="$(terminal_size)"

  while IFS=$'\t' read session_name window_name dir; do
    if [[ -d "$dir" && $window_name != "log" && $window_name != "man" ]]; then
      if session_exists "$session_name"; then
        add_window "$session_name" "$window_name" "$dir"
      else
        new_session "$session_name" "$window_name" "$dir" "$dimensions"
        count=$(( count + 1 ))
      fi
    fi
  done < ~/.tmux-session

  echo "restored $count sessions"
}

case "$1" in
save | restore )
  $1
  ;;
* )
  echo "valid commands: save, restore" >&2
  exit 1
esac

As an alternative, installing tmux-resurrect is also recommended.

Troubleshooting

libevent conflict 

dyld: Library not loaded: /usr/local/lib/libevent-2.0.5.dylib

Try removing libevent and reinstalling. 

$ brew uninstall libevent
$ brew install tmux

Slow ESC response

If ESC responds slowly, for example when used together with vim, add the following to the ~/.tmux.conf file. 

set -sg escape-time 0

Configuration file changes not taking effect

If a tmux server session is running, changes are not applied properly. You need to stop the server and start it again. 

$ tmux kill-server

Unicode characters like ë suddenly being typed

See Terminal emulator#How to enter Unicode characters on Linux.

Unicode characters like e̲ suddenly being typed

See Emoji#Emoji insertion mode.

See also

Favorite site

Configurations

Guides

author Zer0 sitemap