Tmux

How to use popup windows in tmux?

Quick Answer

To create a popup window in tmux (version 3.2+), use the display-popup command followed by the shell command you want to run.

Quick Command Examples

Ctrl+b:

display-popup -E 'ping google.com'

Opens a basic popup with ping google.com

Ctrl+b:

display-popup -w 80% -h 80% -E $SHELL

Opens a large centered popup with your default shell

Ctrl+b:

display-popup -w 80% -h 80% -E htop

Opens htop in a large popup

Detailed Explanation

Popup windows are a powerful feature introduced in tmux 3.2 that allow you to temporarily open floating windows for running commands, viewing information, or performing quick tasks without disrupting your current layout.

Popup Visualization

$ ls -la

total 32

drwxr-xr-x 5 user staff 160 Aug 10 14:23 .

drwxr-xr-x 3 user staff 96 Aug 10 14:22 ..

-rw-r--r-- 1 user staff 1024 Aug 10 14:23 README.md

drwxr-xr-x 12 user staff 384 Aug 10 14:23 src

-rw-r--r-- 1 user staff 2048 Aug 10 14:23 package.json

$ git status

On branch main

Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

htop

[press Escape to close]

Tasks: 127 total, 1 runningLoad average: 0.52 0.58 0.59

PIDUSERPRICPU%MEM%COMMAND

1423user2012.34.2tmux: server

1892user205.73.1vim

2156user202.11.8bash

Popups appear centered by default, floating above your terminal content. They can be customized in size, position, and appearance, and will close when you press Escape or when the command completes (with -E option).

Basic Popup Usage

The basic syntax for creating a popup is:

display-popup [options] [command]

If no command is specified, it opens your default shell. The popup will close when you press Escape or when the command exits (if -E is used).

Common Options for display-popup

Customize your popups with these options:

Size & Position

-w

Width

e.g., -w 80 or -w 50%

-h

Height

e.g., -h 20 or -h 60%

-x

Horizontal position

e.g., -x 10 or -x C for center

-y

Vertical position

e.g., -y 5 or -y C for center

Behavior & Appearance

-E

Auto-close on exit

Close when command completes

-B

Borderless

Don't display a border

-S

Status style

Use status-line style for border

-d

Practical Popup Examples

Here are some useful examples of popup windows:

Quick File Browser

bind-key f display-popup -E "find . -type f | fzf | xargs nvim"

Opens a fuzzy finder in a popup to quickly find and edit files

System Monitoring

bind-key H display-popup -E "htop"

Launch htop process viewer in a popup for quick system monitoring

Quick Note Taking

bind-key N display-popup -E "nvim ~/notes/quick-note.md"

Open a quick note file in a popup editor without disrupting your workflow

Custom Sized Popup

bind-key C display-popup -w 80% -h 60% -E "bash"

Create a large popup shell that takes up most of your screen

Git Status Popup

bind-key g display-popup -w 80% -h 80% -E "git status && echo 'Press any key to close' && read"

Check git status in a large popup that waits for input before closing

Creating Custom Popup Key Bindings

Add these to your ~/.tmux.conf for quick access to popups:

~/.tmux.conf

# Add to ~/.tmux.conf

# Open shell in a popup with Ctrl+b T
bind-key T display-popup -E

# Open htop in a popup with Ctrl+b H
bind-key H display-popup -E "htop"

# Open a large popup with Ctrl+b P
bind-key P display-popup -w 80% -h 80% -E

Using Popups for tmux Commands

Popups can also run tmux commands to display information about your session:

Session List

display-popup -E "tmux list-sessions | cat"

0: dev* (3 windows)

1: logs (1 window)

2: server (2 windows)

Window List

display-popup -E "tmux list-windows | cat"

0: bash* (1 panes)

1: vim (1 panes)

2: logs (2 panes)

Key Bindings

display-popup -E "tmux list-keys | cat"

bind-key -T prefix c new-window

bind-key -T prefix d detach-client

bind-key -T prefix T display-popup -E

Conclusion

Popup windows are a powerful addition to tmux that can significantly improve your workflow by allowing you to quickly access information or run commands without disrupting your current layout.

Experiment with different options and key bindings to find what works best for you. Popups are especially useful for quick tasks that don't require a full pane or window.

←Back to FAQ Index