tmux on macOS with iTerm2 can feel like a magic trick for managing your terminal sessions, but getting it to play nice with iTerm2’s fancy features requires a bit of deliberate setup.
Here’s what a typical tmux session looks like running inside iTerm2:
(base) user@hostname ~ % tmux attach
(base) user@hostname:0
+----------------------------------------------------------------------------+
| pane 1 |
| |
| |
+----------------------------------------------------------------------------+
| pane 2 |
+----------------------------------------------------------------------------+
This isn’t just a basic terminal; it’s iTerm2’s enhanced output, including things like mouse support and true color, all managed by tmux.
The core problem tmux solves is session persistence. You can detach from a tmux session, log out, and later reattach to find everything exactly as you left it. This is invaluable for remote work, long-running processes, or just keeping your workspace organized across reboots.
Internally, tmux works by creating a server process that manages "sessions." Each session can contain multiple "windows" (think tabs), and each window can be split into multiple "panes" (think split views). Your iTerm2 terminal then acts as a client, attaching to these tmux sessions to display them.
The key to making iTerm2 and tmux work well together is ensuring that iTerm2’s advanced features, like mouse support and true color, are passed through to tmux and then rendered correctly by the terminal emulator.
Here’s how you set it up:
1. Install tmux: If you don’t have it already, get it via Homebrew:
brew install tmux
This ensures you have a recent, well-supported version.
2. Configure your .tmux.conf:
This is where the magic happens. Create or edit ~/.tmux.conf and add these lines:
# Enable mouse support
set -g mouse on
# Set terminal type for true color support
set -g default-terminal "tmux-256color"
# Set status bar colors (optional, but nice)
set -g status-style 'bg=#333333,fg=#ffffff'
set -g status-left '#[fg=green]Session: #S #[fg=yellow]#I #[fg=cyan]#P'
set -g status-right '#[fg=cyan]%Y-%m-%d %H:%M'
# Set key bindings for easier window/pane management (optional)
bind-key j command-prompt -p "join pane from: " "join-pane -h -s '%%'"
bind-key c new-window -c '#{pane_current_path}'
bind-key C new-session -c '#{pane_current_path}'
set -g mouse on: This enables mouse support. You can click on panes to select them, scroll within panes, and even resize panes with your mouse. iTerm2 needs to send mouse events, and tmux needs to interpret them.set -g default-terminal "tmux-256color": This is crucial for true color (24-bit color) support. Many modern terminal applications, including iTerm2, support this. By setting this option, you’re telling tmux to advertise that it’s capable of handling 256 colors (and by extension, true color when the terminal emulator supports it), which allows applications running inside tmux to use a wider color palette. iTerm2 will then correctly interpret these color codes.- The status bar lines are for visual flair, making your tmux sessions easier to identify.
- The
bind-keylines are common ergonomic improvements that let you create new windows or sessions starting in the current directory, which is incredibly handy.
3. Configure iTerm2:
Open iTerm2’s preferences (Cmd+,).
- Go to Profiles > [Your Profile] > Terminal.
- Under Emacs/Vim Mode, ensure "Emacs" is selected. This is the default and generally works best with tmux.
- Go to Profiles > [Your Profile] > Advanced.
- Under "Terminal mouse reporting", ensure it’s set to "Enabled". This is usually the default.
- Under "Report terminal size", ensure it’s set to "Enabled". This is also usually the default.
- Crucially, go to Preferences > Profiles > [Your Profile] > Colors. Make sure "Use bold colors" and "Use bright colors" are checked if you want your 256-color/true-color settings to look as intended. For true color, ensure you have a color scheme selected that supports it (most modern ones do).
4. Restart your terminal or tmux server: Close all iTerm2 windows and restart it. Then, start a new tmux session:
tmux new -s my_session
Or attach to an existing one:
tmux attach
Now, when you run applications inside tmux that use colors (like ls --color=auto, vim, or git log), they should render with the correct colors, and you should be able to use your mouse to interact with panes.
The one thing most people don’t realize is that set -g default-terminal "tmux-256color" isn’t just about 256 colors; it’s the token that many modern terminal emulators, including iTerm2, recognize as meaning "I’m a capable terminal that can handle advanced features like true color and mouse reporting when the underlying emulator supports it." Without this, applications inside tmux might fall back to basic ANSI colors, and mouse events might not be passed through correctly.
The next step is usually integrating tmux with your shell’s prompt, making it aware of the tmux environment.