問題の症状

tmuxを使っていて突然スクロールが効かなくなった。具体的には：

  • マウスホイールでのスクロールが無反応
  • iPhone（SSH経由）でもスクロール不可
  • コピーモード（Prefix + s）に入ると右上に [0/0] と表示される
  • スクロールバッファが空だと認識されている状態

環境

  • OS: macOS
  • ターミナル: iTerm2
  • tmux: 既存セッションで発生
  • 設定ファイル: ~/.tmux.conf あり

原因の特定

症状から推測できた原因

[0/0] の表示は、tmuxがスクロールバッファ（履歴）を正しく認識していないことを示している。これは以下が原因：

1. 代替画面設定の競合: alternate-screen の設定が不適切 2. terminal-overrides の不具合: 古い設定による影響 3. 既存ペインの設定継承: 新しい設定が既存ペインに反映されない

設定ファイルの問題箇所

問題があった設定： 
問題のあった設定

set -g terminal-overrides 'xterm*:smcup@:rmcup@'
set -g alternate-screen on  # ←これが問題
set -g history-limit 2000   # ←容量も少なかった
修正後の設定： 
スクロールバッファ設定の修正

set -g history-limit 50000


代替画面を完全に無効化（重要）

set -g terminal-overrides 'xterm*:smcup@:rmcup@'
set -s escape-time 0


明示的にスクロール機能を有効化

set -g mode-keys emacs
set -g status-keys emacs

解決手順

1. 設定ファイルを修正

~/.tmux.confを編集

nano ~/.tmux.conf


上記の修正版設定を適用

2. 設定を再読み込み

tmux source-file ~/.tmux.conf

3. 新しいペイン/ウィンドウでテスト

新しいテスト用ウィンドウを作成

tmux new-window -n test


長い出力でテスト

for i in {1..100}; do echo "Line $i: Test"; done

4. スクロール動作確認

  • マウスホイール: 直接スクロール
  • Prefix + s: コピーモードでスクロール
  • 右上表示: [行数/総行数] が正しく表示されるか確認

重要なポイント

既存ペインは修正されない

重要: 設定変更は新しく作成するペイン/ウィンドウにのみ適用される。既存のペインは古い設定のまま。 対処法： 1. 新しいウィンドウに移行 (推奨) 2. セッション再起動 3. 履歴クリア: tmux clear-history

設定のキーポイント

#### ✅ 有効な設定 

set -g mouse on                    # マウス操作有効
set -g history-limit 50000         # 十分な履歴容量
set -g terminal-overrides 'xterm*:smcup@:rmcup@'  # 代替画面無効化

#### ❌ 問題のある設定 

set -g alternate-screen on         # 代替画面有効（スクロール阻害）
set -g history-limit 2000          # 履歴容量不足

予防策

定期的な設定確認

現在の設定値を確認

tmux show-options -g mouse
tmux show-options -g history-limit
tmux show-options -g alternate-screen

テスト用の長い出力コマンド

設定変更後のテスト用

seq 1 200 | xargs -I {} echo "Test line {}"

推奨設定テンプレート

マウス操作

set -g mouse on


履歴設定

set -g history-limit 50000


スクロール最適化

set -g terminal-overrides 'xterm*:smcup@:rmcup@'
set -s escape-time 0


キーバインド

set -g mode-keys emacs
set -g status-keys emacs


簡単スクロールモード

bind-key s copy-mode
bind-key Escape copy-mode

まとめ

tmuxのスクロール問題は主に 代替画面設定の競合 が原因。特に：

1. alternate-screen on を無効化 2. history-limit を十分な値に設定 3. 新しいペイン/ウィンドウ で設定を有効化

この手順で、iPhone/SSH環境でも快適にスクロールできるようになる。

参考情報

  • tmux公式ドキュメント: terminal-overrides設定
  • iTerm2設定: "Save lines to scrollback in alternate screen mode"
  • SSH環境: ターミナルエミュレータとの連携設定

---

発生日: 2025-07-27 解決時間: 約10分 対象環境: macOS + iTerm2 + tmux