macOS Guide

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.

Verified for macOS Sonoma & Sequoia (Apple Silicon & Intel) · tmux v3.6a
Homebrew (Recommended) Build from Source

Method 1: Homebrew (Recommended)

Homebrew is the most widely used macOS package manager. It gives you the latest stable tmux binary in seconds.

1

Install Homebrew (if needed)

If you don't have Homebrew yet, install it first:

bash

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2

Install tmux

Run the Homebrew install command to fetch the latest stable release:

bash

$ brew install tmux

3

Verify the installation

Confirm tmux is installed correctly:

bash

$ tmux -V

tmux 3.6a

Method 2: MacPorts

For users in the MacPorts ecosystem, tmux is available in the ports tree.

bash

$ 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.

1

Install Xcode Command Line Tools

bash

$ xcode-select --install

2

Install build dependencies

tmux requires libevent and ncurses:

bash

$ brew install automake pkg-config libevent ncurses

3

Clone, configure, build, and install

build.sh

$ git clone https://github.com/tmux/tmux.git

$ cd tmux

$ sh autogen.sh

$ ./configure && make

$ sudo make install

$ tmux -V

macOS-Specific Configuration & Performance Tuning

Tips to get the best tmux experience on macOS, including clipboard, terminal integration, and daemon persistence.

📋 Native Clipboard Integration

macOS uses pbcopy and pbpaste for clipboard access. Add this to ~/.tmux.conf to enable copy-mode clipboard support with vi keybindings:

~/.tmux.conf

# macOS pbcopy integration

bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

bind -T copy-mode-vi MouseDragEnd1Pane 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 Settings → Profiles → Keyboard. This lets you use Option+key combinations in tmux copy mode and readline word hopping (Option+f / Option+b).

🖥️ iTerm2 Control Mode

iTerm2 has native tmux integration via Control Mode (-CC flag). This maps tmux windows and panes directly to native macOS iTerm2 tabs and split windows:

bash

$ tmux -CC

# Or attach to existing session:

$ tmux -CC attach

🚀 Persistent Daemon via launchd

To run tmux as a persistent background user daemon on macOS that starts on login, create a custom agent plist in ~/Library/LaunchAgents/com.user.tmux.plist:

launchctl

$ launchctl load -w ~/Library/LaunchAgents/com.user.tmux.plist

Apple Silicon Architecture & Homebrew Prefix

Ensuring correct PATH resolution on ARM64 macOS machines.

Homebrew Path Differences

On Apple Silicon (M1/M2/M3/M4), Homebrew installs binaries to /opt/homebrew/bin (unlike /usr/local/bin on older Intel Macs). Ensure your ~/.zprofile initializes Homebrew: eval "$(/opt/homebrew/bin/brew shellenv)".

Compiling with pkg-config Flags

When compiling tmux from source on Apple Silicon, pass the explicit Homebrew include and library directories to configure: CFLAGS="-I/opt/homebrew/include" LDFLAGS="-L/opt/homebrew/lib" ./configure.

Ghostty & Alacritty Native GPU Rendering

Modern GPU-accelerated terminals on macOS like Ghostty provide instantaneous text throughput inside tmux with native Metal graphics rendering and 24-bit True Color.

Troubleshooting on macOS

Solutions to common installation, terminfo, and clipboard issues on macOS.

tmux: command not found
tmux is not installed or not in your PATH. If you installed via Homebrew on Apple Silicon, ensure Homebrew's bin directory is in your PATH by adding eval "$(/opt/homebrew/bin/brew shellenv)" to your ~/.zprofile (or ~/.bash_profile), then restart your terminal.
Clipboard not working (copy/paste)
On macOS, tmux's default copy mode doesn't integrate with the system clipboard. Install the 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 in Terminal.app or iTerm2
Add the following to ~/.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)
On older macOS versions (pre-Catalina), clipboard and some system services don't work in tmux sessions without 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".
How to upgrade tmux to the latest version via Homebrew
To update your tmux binary to the latest stable release, run brew update && brew upgrade tmux. After upgrading, restart your tmux server by detaching all sessions and running tmux kill-server, or kill individual sessions with tmux kill-session -t <name>.

Other Install & macOS Alternatives Guides

🪟 Windows

Install tmux on Windows via WSL2, MSYS2, or Cygwin.

Windows Guide →

🐧 Ubuntu / Linux

Install tmux via apt, snap, dnf, pacman, or from source.

Linux Guide →

🤖 macOS AI Terminal (cmux)

Compare tmux with cmux — the native macOS GUI terminal built for AI agents.

cmux vs tmux Guide →