Guide · Open source

How to use Oh my tmux! (.tmux): install and configure

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Oh my tmux! (gpakosz/.tmux) is a self-contained tmux configuration that gives tmux a polished, Powerline-inspired look and adds conveniences such as a secondary C-a prefix and mouse mode toggling. It suits developers who already use tmux and people new to tmux who want a sensible default. After this guide you will be able to install it, know where your customizations belong, and find the main features.

Oh my tmux!gpakosz/.tmux · ★ 25.5k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm tmux 2.6 or newer, plus awk, perl, grep and sed, are installed.
2Back up your config. The README recommends backing up any existing tmux configuration before installing.
3Install. Run the automatic installer or follow the manual steps for ~, $XDG_CONFIG_HOME/tmux or ~/.config/tmux.
4Open the .local file. Edit only the tmux.conf.local or .tmux.conf.local copy, never the main config.
5Set Vim bindings if needed. Set VISUAL or EDITOR to vim to enable vi-style key bindings.
6Try the key bindings. Use <prefix> + to maximize a pane and <prefix> m to toggle mouse mode.

Check the requirements first

Oh my tmux! needs tmux 2.6 or newer. The README lists awk, perl, grep and sed as well. Perl with Time::HiRes support is optional and only adds sub-second timestamps.

The README says it runs on Linux, macOS, FreeBSD, OpenBSD and Windows, but Windows is only supported through WSL or Cygwin, which it describes as not recommended. Outside of tmux, the TERM environment variable must be set to xterm-256color.

tmux 2.6 or newer
awk, perl, grep, sed
Optional: perl with Time::HiRes
TERM set to xterm-256color outside tmux

Install Oh my tmux! automatically or manually

The README suggests backing up your existing configuration before installing. You can install into ~, $XDG_CONFIG_HOME/tmux or ~/.config/tmux. The automatic installer is a single curl command piped to bash.

For a manual install in your home directory, clone the repository, symlink the main config and copy the local customization file. When you install in $XDG_CONFIG_HOME/tmux or ~/.config/tmux, the file names do not start with a dot.

curl -fsSL "https://github.com/gpakosz/.tmux/raw/refs/heads/master/install.sh#$(date +%s)" | bash

Manual installation in your home directory

Use these commands to clone the repository into ~ and link the config. Run them exactly as the README shows.

$ cd
$ git clone --single-branch https://github.com/gpakosz/.tmux.git
$ ln -s -f .tmux/.tmux.conf
$ cp .tmux/.tmux.conf.local .

Customize only the .local file

The README is firm on one rule: never alter the main .tmux.conf or tmux.conf file. Put every customization in your .tmux.conf.local or tmux.conf.local copy. This keeps the main config easy to update.

If you use Vim, setting the VISUAL or EDITOR environment variable to vim enables and further customizes the vi-style key bindings, according to the README.

If a set, bind or unbind in your .local file gets overwritten, the README says to append #!important to that line.

Edit only the .local copy, never the main config
Append #!important to a line if Oh my tmux! overwrites it
Set VISUAL or EDITOR to vim for vi-style key bindings

bind c new-window -c '#{pane_current_path}' #!important

Use the main features and key bindings

The prefix is C-b by default, and this configuration adds C-a as a secondary prefix. The README shows <prefix> as either Ctrl+a or Ctrl+b.

Key features include maximizing a pane to its own window with <prefix> +, toggling mouse mode with <prefix> m, and SSH/Mosh aware username and hostname in the status line. The README notes that maximizing differs from the built-in resize-pane -Z command, because a maximized pane can be split further and stays maximized in its own window.

Copying to the OS clipboard on Linux needs xsel, xclip or wl-copy.

<prefix> + maximizes a pane to a new window
<prefix> m toggles mouse mode
Mouse mode also switches to copy-mode when you select text
Copy to OS clipboard needs xsel, xclip or wl-copy on Linux

Troubleshoot common problems

For a suspected bug, the README says to make sure no tmux client or server is running, then start tmux without loading any configuration. If the issue persists, it asks you to contact the tmux project; otherwise, open an issue on the project.

If the status line is broken or duplicated at the bottom of the screen, the README links it to a mismatch between glib and glibc Unicode widths on some Linux systems, and to iTerm2's Unicode 9 width setting on macOS. Setting LC_CTYPE to a UTF-8 locale may help.

The README also says you do not need to install Powerline itself, only fonts patched with Powerline symbols or the standalone PowerlineSymbols.otf font.

$ tmux -f /dev/null -L test

What people use it for

Give a new tmux setup a polished status bar without writing your own config
Keep SSH and Mosh sessions identifiable by showing hostname and username in the status line
Maximize one pane to its own window while keeping other panes in place
Use vi-style key bindings in tmux if you already work in Vim

Frequently asked questions

Is Oh my tmux! free to use?

Yes, the project is released under the MIT licence, as listed in its repository. The MIT licence lets you use, copy and modify the code, subject to its license terms.

What are the requirements for Oh my tmux!?

You need tmux 2.6 or newer, plus awk, perl, grep and sed. Outside tmux, TERM must be set to xterm-256color. The README lists Linux, macOS, FreeBSD, OpenBSD and Windows through WSL or Cygwin.

Does Oh my tmux! work on Windows?

The README says native Windows is not supported. Windows users can use WSL or Cygwin, which the README describes as not recommended.

Where do I put my customizations?

Put them in .tmux.conf.local, or tmux.conf.local if you installed under XDG or ~/.config. The README says not to change the main .tmux.conf file.

Why are my settings being overwritten?

The README says Oh my tmux! may overwrite set, bind and unbind lines in your .local file. Adding #!important to the end of that line stops this.

What is the difference between Oh my tmux! and tmux-plugin-manager or tmuxinator?

Oh my tmux! is a configuration that changes tmux's look and default behaviour. Tools such as tmux-plugin-manager and tmuxinator are listed as comparable projects, so check their docs if you need plugin management or project layouts instead.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Oh my tmux! suits developers who already use tmux and people new to it who want a polished default look with extra conveniences, especially if they use SSH, Mosh or Vim. It is a poor fit if you want a minimal config without a visual theme, or if you need native Windows support.

Install options & downloads