Home

Awesome

Build
Status GitHub
release GitHub
issues

tmux-yank

Copy to the system clipboard in tmux.

Supports:

Installing

Via TPM (recommended)

The easiest way to install tmux-yank is via the Tmux Plugin Manager.

  1. Add plugin to the list of TPM plugins in .tmux.conf:

    set -g @plugin 'tmux-plugins/tmux-yank'
    
  2. Use <kbd>prefix</kbd><kbd>I</kbd> install tmux-yank. You should now be able to tmux-yank immediately.

  3. When you want to update tmux-yank use <kbd>prefix</kbd><kbd>U</kbd>.

Manual Installation

  1. Clone the repository

    $ git clone https://github.com/tmux-plugins/tmux-yank ~/clone/path
    
  2. Add this line to the bottom of .tmux.conf

    run-shell ~/clone/path/yank.tmux
    
  3. Reload the tmux environment

    # type this inside tmux
    $ tmux source-file ~/.tmux.conf
    

You should now be able to use tmux-yank immediately.

Requirements

In order for tmux-yank to work, there must be a program that store data in the system clipboard.

macOS

Note: Some versions of macOS (aka OS X) have been reported to work without reattach-to-user-namespace. It doesn't hurt to have it installed.

The easiest way to use reattach-to-user-namespace with tmux is use to use the tmux-sensible plugin.

To use it manually, use:

# ~/.tmux.conf
set-option -g default-command "reattach-to-user-namespace -l $SHELL"

If you have tmux 1.5 or newer and are using iTerm2 version 3 or newer then the <kbd>y</kbd> in copy-mode and mouse selection will work without tmux-yank.

To enable this:

  1. Go into iTerm2's preferences.

  2. Go to the "General" tab.

  3. Check "Applications in terminal may access clipboard"

  4. In tmux, ensure set-clipboard is turned on:

    $ tmux show-options -g -s set-clipboard
    set-clipboard on
    

HomeBrew (recommended)

$ brew install reattach-to-user-namespace

MacPorts

$ sudo port install tmux-pasteboard

Linux

If you have tmux 1.5 or newer and are using xterm, the <kbd>y</kbd> in copy-mode and mouse selection will work without tmux-yank. See the tmux(1) man page entry for the set-clipboard option.

Debian & Ubuntu

$ sudo apt-get install xsel # or xclip

RedHat & CentOS

$ sudo yum install xsel # or xclip

Cygwin

Windows Subsystem for Linux (WSL)

Configuration

Key bindings

Default and Preferred Clipboard Programs

tmux-yank does its best to detect a reasonable choice for a clipboard program on your OS.

If tmux-yank can't detect a known clipboard program then it uses the @custom_copy_command tmux option as your clipboard program if set.

If you need to always override tmux-yank's choice for a clipboard program, then you can set @override_copy_command to force tmux-yank to use whatever you want.

Note that both programs must accept STDIN for the text to be copied.

An example of setting @override_copy_command:

# ~/.tmux.conf

set -g @custom_copy_command 'my-clipboard-copy --some-arg'
# or
set -g @override_copy_command 'my-clipboard-copy --some-arg'

Linux Clipboards

Linux has several cut-and-paste clipboards: primary, secondary, and clipboard (default in tmux-yank is clipboard).

You can change this by setting @yank_selection:

# ~/.tmux.conf

set -g @yank_selection 'primary' # or 'secondary' or 'clipboard'

With mouse support turned on (see below) the default clipboard for mouse selections is primary.

You can change this by setting @yank_selection_mouse:

# ~/.tmux.conf

set -g @yank_selection_mouse 'clipboard' # or 'primary' or 'secondary'

Controlling Yank Behavior

By default, tmux-yank will exit copy mode after yanking text. If you wish to remain in copy mode, you can set @yank_action:

# ~/.tmux.conf

set -g @yank_action 'copy-pipe' # or 'copy-pipe-and-cancel' for the default

Mouse Support

tmux-yank has mouse support enabled by default. It will only work if tmux's built-in mouse support is also enabled (with mouse on since tmux 2.1, or mode-mouse on in older versions).

To yank with the mouse, click and drag with the primary button to begin selection, and release to yank.

If you would prefer to disable this behavior, or provide your own bindings for the MouseDragEnd1Pane event, you can do so with:

# ~/.tmux.conf

set -g @yank_with_mouse off # or 'on'

If you want to remain in copy mode after making a mouse selection, set @yank_action as described above.

vi mode support

If using tmux 2.3 or older and using vi keys then you'll have add the following configuration setting:

# ~/.tmux.conf

set -g @shell_mode 'vi'

This isn't needed with tmux 2.4 or newer.

Screen-cast

screencast
screenshot

Note: The screen-cast uses <kbd>Control</kbd><kbd>y</kbd> for "put selection". Use <kbd>Y</kbd> in v2.0.0 and later.

Other tmux plugins

License

MIT