tmux Troubleshooting and Debugging

tmux•Permalink

tmux commands and config snippets for diagnosing key bindings, options, environment issues, TERM problems, and server resets.

View

Standard Detailed Compact

Export

Copy the compact sheet, download it, or print it.

Download

`D` dense toggle · `C` copy all

Debug and introspection

Inspect bindings, options, environment, and server state.

Show global options

Inspect current global configuration.

↗#

bashANYtmuxshow-options

bash

tmux show-options -g

Useful when debugging unexpected behavior from config files.

Show window options

Inspect per-window settings.

↗#

bashANYtmuxshow-window-options

bash

tmux show-window-options -g

Helps with issues like synchronization, mode keys, or layout-related settings.

List key bindings

Dump the default and custom key tables.

↗#

bashANYtmuxlist-keysbindings

bash

tmux list-keys

A fast way to verify what is actually bound.

Show tmux environment

Inspect environment variables known to tmux.

↗#

bashANYtmuxenvironment

bash

tmux show-environment

Helpful when debugging PATH, SSH agent, or locale issues.

Show server info

Print internal server details.

↗#

bashANYtmuxinfo

bash

tmux info

Useful for low-level debugging.

Common problems and fixes

Practical snippets for frequent tmux headaches.

Set a modern default terminal

Use a terminal definition with 256-color/feature support.

↗#

tmuxANYtmuxtermcolors

tmux

set -g default-terminal "tmux-256color"

Terminal capability mismatches are a common reason for broken colors or key behavior.

Preserve selected environment variables

Update tmux with variables from the client environment.

↗#

tmuxANYtmuxenvironmentssh-agent

tmux

set -g update-environment "DISPLAY SSH_AUTH_SOCK SSH_AGENT_PID WINDOWID XAUTHORITY"

Useful when SSH agent forwarding or GUI-related variables disappear after attaching.

Restart the tmux server

Terminate the tmux server entirely.

↗#

bashANYtmuxkill-server

bash

tmux kill-server

Nuclear option for clearing server-wide state; it ends all sessions.

Reload config with shell tracing

Verify config sourcing from a shell wrapper.

↗#

bashANYtmuxdebugconfig

bash

sh -x -c "tmux source-file ~/.tmux.conf"

Useful when a shell wrapper or plugin bootstrap script is involved.

More in tmux

tmux Plugins and Productivity Setup

tmux plugin manager patterns, TPM setup, and common plugin snippets for restoring sessions, sensible defaults, and clipboard workflows.

tmux Remote Sessions, SSH, and Pairing

tmux patterns for remote servers, resilient SSH sessions, multi-client visibility, and collaboration workflows.

tmux Scripting, Formats, and Automation

tmux commands for listing state, using format strings, conditional logic, send-keys automation, and repeatable workspace bootstrapping.

tmux Configuration and Customization

tmux .tmux.conf settings for prefix changes, mouse support, indexing, reloading, and status bar customization.

tmux Copy Mode, Scrollback, and Clipboard

tmux copy-mode commands, scrollback capture, search, buffers, and clipboard configuration patterns.

tmux Sessions, Windows, and Panes

Core tmux commands and interactive shortcuts for managing sessions, windows, panes, splits, and layouts.

Recommended next

No recommendations yet.

Browse all sheets →