eiji.page

tmuxの設定の書き方！構文からトラブルシューティングまで

#tmux

tmuxはデフォルト設定でも便利ですが、カスタマイズするともっと便利になります。今回はtmux初心者向けに「tmuxの設定ファイルの書き方」を解説します。

※tmux関係の記事は他にも書いています。「まだ知らないぞ」ってことがあれば一緒にご覧ください。

設定ファイルの場所

tmuxの設定ファイルは次のいずれかに書きます。

  • ~/.tmux.conf
  • ~/.config/tmux/tmux.conf

設定ファイルの優先順位

tmuxは次の順序で設定ファイルを探して、存在すればその設定を追加で読み込んでいきます。つまり、同じオプション・キーバインドを設定したら後から読み込まれるものが優先されます。

  1. /etc/tmux.conf（環境によって違うため後述。システム全体の設定）
  2. ~/.tmux.conf
  3. $XDG_CONFIG_HOME/tmux/tmux.conf
  4. ~/.config/tmux/tmux.conf

基本は~/.tmux.confか~/.config/tmux/tmux.confのどちらかだけで問題ありません。

設定ファイルの構文（基本）

※まずは書き方だけで、実際のコマンドの意味などは後で解説します。

tmuxの設定ファイルの構文は結構単純です。tmux foo barといったコマンドからtmuxを取り除いたものをつらつらと書いていくだけです。

たとえば、ステータスラインの色を設定するコマンドは コマンドラインからだと 次のように実行できます。

Terminal window
tmux set-option -g status-style bg=cyan

これを 設定ファイルに書くと こうなります。

tmux.conf
set-option -g status-style bg=cyan

コメントアウト

設定ファイルでは#を使ってコメントも書けます。

tmux.conf
# いぇーい。見てるぅ〜？コメントだよ！
set-option -g status-style bg=cyan

長い行を複数行に分けて書く

長めの設定は1行だと見づらいです。そんなときは\を活用しましょう。行末に\があると、その行と次の行は結合されてから処理されます。

tmux.conf
# lazygitをポップアップで開くキーバインドを prefix + g に設定
bind-key g display-popup -w 95% -h 90% -E \
  -d '#{pane_current_path}' \
  'lazygit --use-config-dir=$HOME/.config/lazygit'

設定の反映方法

一番先に知っておいてほしいのが設定の反映方法です。

次のコマンドで反映できます。

Terminal window
# 設定ファイルの場所は各自に合わせて書き換え
tmux source-file ~/.tmux.conf

でも毎回これを入力するのは面倒ですよね。次の設定が便利です。

tmux.conf
# 設定ファイルの場所は各自に合わせて書き換え
bind-key r source-file ~/.tmux.conf \; display-message "Reload Config!!"

prefix+rを入力すると、設定ファイルが読み込まれて反映できます。
ファイル読み込みだけだと 本当に読み込まれたかが分かりづらい ため、display-messageでメッセージを表示しています。

※途中の\;はbind-keyのセクションで解説します。

set-option オプションの設定

オプションの設定はset-option（略：set）を使います。

# どちらも同じ
set-option -g status-style bg=cyan
set -g status-style bg=cyan

細かいオプションの種類

先ほどから出てくる-gが気になりますよね。set-optionでは、どの単位でそのオプションを適用するかを決められます。

  • -s: サーバー（ソケット）単位
    • 99%の人は使いません
    • tmux -Lオプションで別のソケットを用意する時
  • -g：全セッション単位
    • 基本これ
  • 指定なしの場合：特定のセッション単位
  • gw：全ウィンドウ単位
    • ウィンドウに関わるやつは基本これ
  • w：特定のウィンドウ単位
  • p：特定のペイン単位

※ウィンドウ単位にはset-window-optionという設定方法もありましたが、これは古い書き方です。

具体的な例を見ていきましょう。

prefixの変更

デフォルトのprefixキーはCtrl+bですが、これを変更できます。筆者は押しやすいCtrl+sにしています。

set-option -g prefix C-s

Ctrl+◯をC-◯のように書きます。Altキー（Metaキー）の場合はM-◯のように書きます。

MacでoptionキーをAltキー（Metaキー）として扱いたい場合、ターミナル側で別途設定が必要です（Weztermの例は後半で説明）。

history-limitの上限緩和

tmuxでさかのぼれる行数はhistory-limitで決まっており、デフォルト値は2000です。

ログだともう少し多いほうがうれしいため、筆者は5000に設定しています。

set-option -g history-limit 5000

その他オプション

すべてのオプションはman 1 tmuxのOPTIONSに書いてあります。

bind-key キーバインドの設定

キーバインドはbind-key（略：bind）で設定します。

# どちらも同じ
bind-key C set-option -g status-style bg=cyan
bind C set-option -g status-style bg=cyan

bind-key キー 実行コマンドという形式です。実行コマンドはtmux foo barのtmuxを抜いた部分です。

上記の例ではprefix+shift+cに割り当てています。

bind-keyのキーの書き方

a-zA-Zなど ほとんどのキーはそのまま 書きます。その他の特殊なキーはこんな感じ。

Up, Down, Left, Right
F1 to F12, Home, IC (Insert)
NPage/PageDown/PgDn, PPage/PageUp/PgUp
Space, Tab, BSpace, BTab, DC (Delete), End
Enter, Escape

クオートは別のクオートで囲みます。

bind-key '"' split-window
bind-key "'" new-window

修飾キーはこんな風に書きます。

設定したいキーtmux.conf
CtrlC-◯か^◯
Shift+◯S-◯。S-Upなど。アルファベットはS-は使わずZのように大文字
Alt+◯M-◯

prefixなしで割り当てる

prefixなしでキーを設定したい場合、次のように-nまたは-T rootと書きます。

bind-key -n M-o display-message "Foo!"
bind-key -T root M-o display-message "Foo!"

説明付きが便利

bind-keyでは-Nオプションで説明が書けます。

bind-key -N "再読み込み" r source-file ~/.tmux.conf \; display-message "Reload Config!!"

これを書いておくと、prefix+?のキーバインド一覧に表示されるのでおすすめです。

複数のコマンドを割り当てるには？

複数のコマンドを連続して実行するには\;で区切ります。

bind-key r source-file ~/.tmux.conf \; display-message "Reload Config!!"

;だけや他の書き方もありますが、推奨されているのは\;のようです。

でももっと見やすくしたい

オプションが増えていくとどこからが実行コマンドなのか分かりづらくなります。そんなときは{}で囲ってあげるといいです。

bind-key -N "再読み込み" r { source-file ~/.tmux.conf ; display-message "Reload Config!!" }

{}を使う場合は、コマンドの区切りは;です。これでも見づらい場合は改行しましょう。

bind-key -N "再読み込み" r {
  source-file ~/.tmux.conf ; \
  display-message "Reload Config!!"
}

実践的なカスタマイズ例

座学のような構文説明はここまでです。ここからは実際の筆者のカスタマイズを交えた解説をします。

ウィンドウ分割

まずはウィンドウ分割（split-window）です。紛らわしいですが増えるのはペインです。

# ￥(\) | でペインを縦に分割する
bind-key \\ split-window -h -c '#{pane_current_path}'
bind-key | split-window -h -c '#{pane_current_path}'


# - でペインを横に分割する
bind-key - split-window -v -c '#{pane_current_path}'

-cでディレクトリを指定してペインを開きます。

#{pane_current_path}というのはtmuxの変数です。「現在のペインのカレントディレクトリ」を表します。man 1 tmuxのFORMATSに詳しく載っています（変数は200以上あってめっちゃ多いです）。

ペイン間移動

ペイン間の移動はVimライクにしています。

# Vimのキーバインドでペインを移動する
bind-key h select-pane -L
bind-key j select-pane -D
bind-key k select-pane -U
bind-key l select-pane -R

この設定ではselect-paneで方向を指定しています。

ウィンドウ間移動

ウィンドウ間の移動は次のようにprefixなしで設定しています。

bind-key -n M-p previous-window
bind-key -n M-n next-window

ウィンドウの並び変更

ウィンドウの並び順を変更する設定もしてます。

bind-key -n M-h swap-window -t -1 \; previous-window
bind-key -n M-l swap-window -t +1 \; next-window

M-hで「今のウィンドウを前に並び替え」、M-lは後ろに並び替えです。

ペインのリサイズ

ペインのリサイズもVimライクにしています。

# Vimのキーバインドでペインをリサイズする
# -r 少しの間prefixなしで連続入力できる
bind-key -r H resize-pane -L
bind-key -r J resize-pane -D
bind-key -r K resize-pane -U
bind-key -r L resize-pane -R

-rオプションを使うと、少しの間はprefixなしで連続入力できます。

  • -rなし：prefix+H、prefix+H、prefix+H
  • -rあり：prefix+H、H、H

連続入力ができる時間はrepeat-timeというオプションで変更できます。デフォルトは500ミリ秒です。

# 連続入力できる時間(ミリ秒)
set-option -g repeat-time 1000

条件分岐をする

if-shell（略：if）を使うと、条件分岐が書けます。

if-shell "判定コマンド" "成功時のコマンド" "失敗時のコマンド"

"判定コマンド"は/bin/shで実行されます。これが成功すれば"成功時のコマンド"、失敗なら"失敗時のコマンド"が実行されます。

一番単純な例を見てみましょう。

# 失敗時は省ける
if-shell "true" "bind-key q display-message 'Ninja!'"

※trueは常に成功するのでキーバンドは設定されます。

which コマンド名など、コマンドの有無とかで使えそうです。

ペイン間移動（折り返し無し）

もっと便利なif-shellを見てみましょう。

bind-key h if-shell -F '#{pane_at_left}' '' 'select-pane -L'
bind-key j if-shell -F '#{pane_at_bottom}' '' 'select-pane -D'
bind-key k if-shell -F '#{pane_at_top}' '' 'select-pane -U'
bind-key l if-shell -F '#{pane_at_right}' '' 'select-pane -R'

さて。ここまでの復習のような設定です。bind-keyはすでに説明しました。ではキーバインド入力時に実行されるコマンドの部分を見てみましょう。

select-paneの仕様

select-paneはそのままだと折り返しになります。たとえばselect-pane -Lだと「左のペインに移動」となりますが、一番左のペインで実行すると一番右のペインへ移るのです。

if-shellのFオプション

if-shellで-Fを使うと、判定部分はコマンドの実行ではなく変数展開となります。

if-shell -F '#{pane_at_left}' '' 'select-pane -L'

#{pane_at_left}は「ペインがウィンドウの左側なら1を返す」tmuxの変数です（詳細：man 1 tmuxのFORMATS）。

つまり上記のif-shellは、「左にペインが無いなら何もしない。あれば左のペインに移動」という条件分岐です。

マウス操作

マウスによるスクロールやクリックを使うにはmouseオプションをonにします。

set-option -g mouse on

tmuxのペインのスクロールよりも、VimやlazygitといったTUI内のスクロールが優先されます。ドラッグの範囲選択も同様です。

過去のtmuxではスクロール優先やコピーモードとの兼ね合いがあって、WheelUpPaneやWheelDownPaneに自作の複雑なキーバインドを割り当てる方も多かったです。現在はオプションの設定だけで問題ありません。

FAQとトラブルシューティング

随時追記します。

設定が反映されない

原因がいくつかあるので順に試してください。

読み込むファイルがあっているか

「設定の反映方法」で書きましたが、読み込むファイルを確認しましょう。

Terminal window
tmux source-file <ここ合ってる？>

上書き形式ってことに注意

たとえば「bind-keyで設定したのを削除したけど反映されない」というケースがあります。これはsource-fileが単にファイルを読み込むだけだからです。同じオプション・キーバインドなら上書きされますが、削除しただけの設定はまだ残っています。

キーバインドの解除にはunbind-keyを実行します。

Terminal window
tmux unbind-key o

set-optionの場合はデフォルト値で上書きします。「デフォルト値なんて知らん！」という場合、tmuxのDeepWikiやご愛用のAIに聞けば一発です。

構文ミスかも

構文などがあっているか確認しましょう。設定ファイルだけじゃなくてtmux 〇〇のような「シェルでの実行」や、prefix+:による「tmuxのコマンドラインでの実行」だと確認しやすいです。

筆者がよくやるミスはクオートの書き忘れです。

バージョンは最新？

tmux -Vでtmuxのバージョンが最新であるか確認してください。

ちなみに「どのバージョンから使えるんだ？」と更新履歴を確認したくなったらCHANGESを見たりtmuxのDeepWikiで聞くのがいいでしょう。

プラグインとの競合

tmuxでプラグインを使っている場合、プラグインマネージャーの初期化処理が最後になっているか確認しましょう。

# ...
run '~/.tmux/plugins/tpm/tpm'

最後以外に書いてしまうと、一部の設定が反映されません。

一時的に違う設定ファイルを読み込みたい

tmuxに関わるスクリプトの動作確認や録画CLIのvhsを使う場合、一時的に別の設定ファイルを使いたくなるでしょう。その場合は起動時のオプション-fで指定します。

Terminal window
tmux -L default kill-server
tmux -f ~/foo/bar.conf

前のサーバーが残ったままだと設定も残ったままになるため、kill-serverしてから起動しましょう。

optionキーは使えないの？

WindowsキーボードだとAltキー（Metaキー）をM-◯として設定できます。MacでoptionでもM-◯を設定したい場合、ターミナル側の設定が必要です。

たとえばWeztermの場合、次のように書きます。

local wezterm = require("wezterm")
local config = {}
local target = wezterm.target_triple
local key_table = {}


local function append_array(array, other)
  for _, value in ipairs(other) do
    table.insert(array, value)
  end
end


if target:find("darwin") then
  local mac_key_table = {
    { key = "h", mods = "OPT", action = { SendKey = { key = "h", mods = "ALT" } } },
    { key = "l", mods = "OPT", action = { SendKey = { key = "l", mods = "ALT" } } },
    { key = "n", mods = "OPT", action = { SendKey = { key = "n", mods = "ALT" } } },
    { key = "o", mods = "OPT", action = { SendKey = { key = "o", mods = "ALT" } } },
    { key = "p", mods = "OPT", action = { SendKey = { key = "p", mods = "ALT" } } },
    { key = "q", mods = "OPT", action = { SendKey = { key = "q", mods = "ALT" } } },
    { key = "s", mods = "OPT", action = { SendKey = { key = "s", mods = "ALT" } } },
    { key = "¥", action = wezterm.action.SendKey({ key = "\\" }) },
  }
  append_array(key_table, mac_key_table)
end


config.keys = key_table
return config

escape-timeって変えた方がいいの？

古い記事を見ると次のような記述を見ることがあるかもしれません。

set-option -s escape-time 50

escape-timeはキーがEscであると判定するための時間の設定値です。以前はこの値が500であったため、VimやNeovimで多用するEscキーが「なんだか遅い」というときにこの値を小さくしていました。

しかしtmuxのバージョンが3.5以上であれば escape-timeの変更は不要 です。デフォルト値が10に変わっています。

システム全体で設定したい

ssh先にtmuxをインストールして使うような複数人で運用する環境もあるでしょう。そんなときはユーザー単位ではなく「システム全体」で共通分だけ設定したいかもしれません。

システム全体として設定したい場合は/etc/tmux.confなどに書きます。この場所は端末によって違うため、manコマンドのFILESセクションで確認してください。

Terminal window
man 1 tmux

たとえば筆者はMacのHomebrewでインストールしたため、/opt/homebrew/etc/tmux.confがシステム全体設定の場所でした。ただ、筆者にはシステム全体の設定は必要ないのでファイルは作っていません。

少々長くなりましたが、tmuxの設定ファイルの書き方を解説しました。tmuxはドキュメントを漁るたびに新発見があります。

#tmux
記事一覧に戻る

関連記事

すべての記事を見る