How do I install tmux on macOS using Homebrew?

Open Terminal and run brew install tmux. Verify with tmux -V.

Install tmux on macOS — Homebrew & MacPorts

Install tmux on macOS in one line

brew install tmux — that is the whole install for most people. The rest of this page covers MacPorts, building from source, and macOS-specific setup such as clipboard integration and true colour.

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

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 needs libevent and ncurses; building from git also needs autoconf, automake and pkg-config. utf8proc gives correct emoji and wide-character widths on macOS (Homebrew's own build enables it):

bash

$ brew install autoconf automake pkgconf libevent ncurses utf8proc

3

Clone, configure, build, and install

build.sh

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

$ cd tmux

$ sh autogen.sh

$ ./configure --enable-utf8proc && 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 (full walkthrough in the iTerm2 + tmux guide):

bash

$ tmux -CC

# Or attach to existing session:

$ tmux -CC attach

🚀 Persistent Daemon via launchd

To start a detached tmux session automatically when you log in, save this as ~/Library/LaunchAgents/com.user.tmux.plist (use /usr/local/bin/tmux on Intel Macs):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.user.tmux</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/tmux</string>
    <string>new-session</string><string>-d</string><string>-s</string><string>main</string>
  </array>
  <key>RunAtLoad</key><true/>
</dict>
</plist>

Then load it (or log out and back in) and attach with tmux attach -t main:

launchctl

$ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.tmux.plist

For the full set of session commands and lifecycle options, see tmux session management.

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". In terminals that support OSC 52 (iTerm2 with “Applications in terminal may access clipboard” enabled, Ghostty, Kitty, WezTerm) tmux's default set-clipboard external copies to the macOS clipboard without any extra tools.

Colors not rendering correctly in Terminal.app or iTerm2

Add set -g default-terminal "tmux-256color" and set -as terminal-features ",xterm-256color:RGB" to ~/.tmux.conf, then run tmux kill-server. If programs complain about an unknown terminal tmux-256color (common before macOS 14 Sonoma, whose system terminfo lacks that entry; Homebrew's tmux uses screen-256color there for this reason), use screen-256color instead. iTerm2, Ghostty, WezTerm and Kitty support 24-bit colour; Terminal.app has historically supported only 256 colours, so tmux will approximate 24-bit themes there.

Do I still need reattach-to-user-namespace?

You only need reattach-to-user-namespace with tmux older than 2.6 (released 2017); newer tmux includes its functionality, so remove it from old configs if you see errors. With an old tmux, clipboard and some system services fail without it. 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. Sessions started before the upgrade still run the old server, and the new client may refuse to talk to it with a protocol version mismatch error. Save your work, run tmux kill-server, then start tmux again. MacPorts users run sudo port selfupdate && sudo port upgrade tmux.

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 →