Install tmux on macOS
macOS is the primary development platform for many tmux power users. tmux runs natively on macOS via Homebrew or MacPorts, and can also be compiled from the latest source. Choose your method below.
Method 1: Homebrew (Recommended)
Homebrew is the most widely used macOS package manager. It gives you the latest stable tmux binary in seconds.
Install Homebrew (if needed)
If you don't have Homebrew yet, install it first:
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Install tmux
Run the Homebrew install command to fetch the latest stable release:
$ brew install tmux
Verify the installation
Confirm tmux is installed correctly:
$ tmux -V
tmux 3.6a
Method 2: MacPorts
For users in the MacPorts ecosystem, tmux is available in the ports tree.
$ sudo port install tmux
$ tmux -V
Method 3: Build from Source
Build the absolute latest version from the official GitHub repository. Requires Xcode Command Line Tools.
Install Xcode Command Line Tools
$ xcode-select --install
Install build dependencies
tmux requires libevent and ncurses:
$ brew install automake pkg-config libevent ncurses
Clone, configure, build, and install
$ git clone https://github.com/tmux/tmux.git
$ cd tmux
$ sh autogen.sh
$ ./configure && make
$ sudo make install
$ tmux -V
macOS-Specific Configuration
Tips to get the best tmux experience on macOS, including clipboard and terminal integration.
📋 Clipboard Integration
macOS uses pbcopy and pbpaste for clipboard access. Add this to ~/.tmux.conf to enable copy-mode clipboard support:
# macOS clipboard integration
$ set -g @plugin 'tmux-plugins/tmux-yank'
# OR manually:
$ bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
⌨️ Option Key as Meta in Terminal.app
In macOS Terminal.app, enable "Use Option as Meta key" under Preferences → Profiles → Keyboard. This lets you use Option+key combinations in tmux copy mode and readline.
🖥️ iTerm2 Control Mode
iTerm2 has native tmux integration via Control Mode (-CC flag). This maps tmux windows and panes to native iTerm2 tabs and splits:
$ tmux -CC
# Or attach to existing session:
$ tmux -CC attach
Troubleshooting on macOS
tmux: command not found
eval "$(/opt/homebrew/bin/brew shellenv)" to your ~/.zprofile (Apple Silicon) or ~/.bash_profile (Intel), then restart your terminal.
Clipboard not working (copy/paste)
tmux-yank plugin via TPM (set -g @plugin 'tmux-plugins/tmux-yank'), or manually bind copy-mode to pbcopy: bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy". Also ensure mouse mode is enabled: set -g mouse on.
Colors not rendering correctly
~/.tmux.conf to enable full 256-color and true-color support: set -g default-terminal "tmux-256color" and set -ga terminal-overrides ",*256col*:Tc". Also ensure your terminal emulator (iTerm2 or Terminal.app) has 256-color support enabled in its profile settings.
reattach-to-user-namespace errors (older macOS)
reattach-to-user-namespace. Install it with brew install reattach-to-user-namespace and add to ~/.tmux.conf: set -g default-command "reattach-to-user-namespace -l $SHELL".