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. For example: Ctrl+b : display-popup -w 80% -h 60% -E "htop" will open htop in a centered popup that takes 80% of the width and 60% of the height. Use -E to close the popup when the command exits, and customize size with -w and -h options.

# Open a basic popup with a command
Ctrl+b :display-popup -E "ls -la"

# Open a large centered popup with a shell
Ctrl+b :display-popup -w 80% -h 80% -E "$SHELL"

# Open a popup for file browsing
Ctrl+b :display-popup -w 80% -h 80% -E "ranger"

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.

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:

-E - Close the popup automatically when the command exits
-w WIDTH - Set the width (e.g., -w 80 for 80 cells or -w 50% for 50% of screen)
-h HEIGHT - Set the height (e.g., -h 20 for 20 cells or -h 60% for 60% of screen)
-x X - Set the horizontal position (e.g., -x 10 or -x C for center)
-y Y - Set the vertical position (e.g., -y 5 or -y C for center)
-B - Don't display a border
-S - Use the status-line style for the popup's border
-d PATH - Start the popup in the specified directory

Practical Popup Examples

Here are some useful examples of popup windows:

1. Quick file browser:

# Using ranger file manager
display-popup -E -w 80% -h 80% "ranger"

# Using a simple file list
display-popup -E "find . -type f | sort | fzf"

2. System monitoring:

# Process viewer
display-popup -E -w 80% -h 80% "htop"

# Network monitor
display-popup -E "nload"

# Disk usage
display-popup -E "ncdu"

3. Quick notes or text editing:

# Open a quick editor
display-popup -E -w 80% -h 80% "${EDITOR:-vim} /path/to/notes.txt"

# Create a new note with timestamp
display-popup -E "vim ~/notes/note-$(date +%Y%m%d-%H%M%S).md"

4. Command output viewer:

# View git log in a popup
display-popup -E "git log --oneline --graph --all"

# View recent commands
display-popup -E "history | tail -n 50"

Creating Custom Popup Key Bindings

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

# Add to ~/.tmux.conf

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

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

# Open file browser in a popup with Ctrl+b F
bind-key F display-popup -E -w 80% -h 80% "ranger"

# Open calendar in a popup with Ctrl+b C
bind-key C display-popup -E "cal -3"

Using Popups for tmux Commands

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

# Show session list in a popup
display-popup -E "tmux list-sessions | cat"

# Show key bindings in a popup
display-popup -E "tmux list-keys | less"

# Show current tmux options
display-popup -E "tmux show-options -g | less"

←Back to FAQ Index