Oh my tmux!: install, customize and update

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

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

What Oh my tmux is

Oh my tmux is one person's tmux setup, published by Gregory Pakosz (its copyright line starts in 2012). It is not a plugin and not part of tmux: it replaces your ~/.tmux.conf with a long file (2,132 lines in the version we tested) that sets options, rebinds keys and draws the status line with embedded shell code.

What you get, according to its README and what we saw when we loaded it: a Powerline-inspired status line with uptime, battery, user and host name (SSH and Mosh aware), Ctrl+a as a secondary prefix while Ctrl+b keeps working, a key to maximize any pane into its own window, a mouse toggle, copy to the system clipboard, and built-in TPM support. This is how it looks on a real tmux 3.8, installed with the manual steps above into a temporary home directory:

Real screenshot · tmux 3.8

Install Oh my tmux

Requirements (from the README): tmux 2.6 or newer on Linux, macOS, FreeBSD, OpenBSD or Windows through WSL (Cygwin works but is slow and not recommended); awk, perl, grep and sed; and TERM=xterm-256color outside tmux. The installer also needs bash and git. Back up your own config first if you care about it.

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

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

$ git clone --single-branch https://github.com/gpakosz/.tmux.git ~/.local/share/tmux/oh-my-tmux
$ mkdir -p ~/.config/tmux
$ ln -s ~/.local/share/tmux/oh-my-tmux/.tmux.conf ~/.config/tmux/tmux.conf
$ cp ~/.local/share/tmux/oh-my-tmux/.tmux.conf.local ~/.config/tmux/tmux.conf.local

What the installer does, read from install.sh at commit 58a3dcc (8 August 2026):

1. Checks it is safe to run

   It refuses to run as root, without bash, without tmux, git, perl, sed or awk, and from inside tmux ("tmux is currently running, please terminate the server"; set PERMISSIVE=true to override).

2. Picks a location

   $XDG_CONFIG_HOME/tmux/tmux.conf if XDG_CONFIG_HOME is set, otherwise ~/.config/tmux/tmux.conf if ~/.config exists, otherwise ~/.tmux.conf. On most Linux desktops ~/.config exists, so you get the XDG location. The repository is cloned to ~/.local/share/tmux/oh-my-tmux.

3. Backs up what is there

   Existing ~/.tmux.conf, ~/.tmux.conf.local and the XDG files are renamed with a timestamp suffix such as ~/.tmux.conf.20261028175812.4242. Old symlinks are deleted. The whole ~/.config/tmux and ~/.tmux directories are renamed the same way.

4. Links the config and copies the .local file

   It symlinks the config file to the clone's .tmux.conf and copies .tmux.conf.local next to it, ready for you to edit.

We ran the manual home-directory install on 28 October 2026 in a temporary home directory with tmux 3.8 and with Ubuntu's tmux 3.4: both started without configuration errors (3.4 logged one harmless "no current client" message from Oh my tmux's background setup). The sandbox we test in does not allow piping a remote script into a shell, so the installer itself was read, not run.

What it changes in tmux

Values read with show-options after loading Oh my tmux with no edits to .tmux.conf.local, compared with a tmux 3.8 server with no config:

Oh my tmux key bindings

<prefix> below means Ctrl+b or Ctrl+a. Every key was checked with list-keys on tmux 3.8. The third column shows what the same key does in stock tmux 3.8, so you know what you give up:

In vi copy mode, v starts a selection, Ctrl+v toggles block selection, H and L jump to the start and end of the line, y copies and Escape cancels. The new tmux 3.8 keys that Oh my tmux does not touch, such as Ctrl+b * for a floating pane and Ctrl+b @, keep working. To keep every stock binding and only add Oh my tmux keys that do not clash, set tmux_conf_preserve_stock_bindings=true in .tmux.conf.local; with it, n, p, l, m, - and Tab were back to the stock commands in our test. All default tmux keys are on the cheat sheet.

Customize it in .tmux.conf.local

The file has two kinds of lines. Shell-style variables such as tmux_conf_theme_status_left="…" are read by Oh my tmux's own code, and normal tmux commands go in the user customizations section near the end:

# More scrollback and the status line at the top
set -g history-limit 50000
set -g status-position top

# Use only Ctrl+a as the prefix
set -gu prefix2
unbind C-a
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# If Oh my tmux overrides a line, mark it #!important
bind c new-window -c '#{pane_current_path}' #!important

Lines ending in #!important are applied again after Oh my tmux has set itself up, which is the fix when one of your set, bind or unbind lines seems to be ignored. In our test, set -g history-limit 20000 #!important and a plain set -g status-position top both took effect.

Useful variables, all in the same file:

Theme colors

The theme uses 17 numbered colors, tmux_conf_theme_colour_1 to tmux_conf_theme_colour_17, which the other tmux_conf_theme_* variables refer to. Change a number to recolor everything that uses it. The sample file also has a commented "ansi" set that uses your terminal's palette instead of fixed hex colors:

tmux_conf_theme_colour_4="#00afff"    # light blue: current window, active border
tmux_conf_theme_colour_5="#ffff00"    # yellow: session name, messages
tmux_conf_theme_colour_10="#ff00af"   # pink: uptime section
tmux_conf_theme_colour_16="#d70000"   # red: user name section

Status line and Powerline separators

The left and right parts come from tmux_conf_theme_status_left and tmux_conf_theme_status_right. A | starts a new colored section and a , a sub-section. Normal tmux formats work, plus Oh my tmux's own variables such as #{battery_percentage}, #{battery_bar}, #{uptime_d}, #{loadavg}, #{hostname_ssh}, #{username}, #{pretty_pane_current_path}, #{prefix}, #{mouse} and #{synchronized}:

tmux_conf_theme_status_left=" ❐ #S | #{pretty_pane_current_path} "
tmux_conf_theme_status_right=" #{prefix}#{mouse} , %R , %d %b | #{username}#{root} | #{hostname} "

These strings go through strftime like tmux's own status-left, so write %% for a literal percent sign. For the Powerline arrow look you need a font with Powerline symbols (a patched or Nerd Font, or PowerlineSymbols.otf), not the Powerline program. Then set the separators:

tmux_conf_theme_left_separator_main=''
tmux_conf_theme_left_separator_sub=''
tmux_conf_theme_right_separator_main=''
tmux_conf_theme_right_separator_sub=''

You can add your own #{name} variables by writing POSIX shell functions at the end of the file, below the # EOF line, as the sample file explains.

Use TPM plugins with Oh my tmux

Oh my tmux has TPM support built in. List plugins in .tmux.conf.local with the usual syntax, and do not add set -g @plugin 'tmux-plugins/tpm' or the run '~/.tmux/plugins/tpm/tpm' line anywhere:

set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'

Plugins are installed and updated automatically when tmux starts and when you reload (turn that off with tmux_conf_update_plugins_on_launch=false and tmux_conf_update_plugins_on_reload=false). The keys differ slightly from plain TPM: Ctrl+b I installs, Ctrl+b u (lowercase) updates and Ctrl+b Alt+u removes plugins you deleted from the list. Plugins go to ~/.tmux/plugins, or to plugins next to tmux.conf in the XDG layout. Variables that plugins add to the status line can be used in tmux_conf_theme_status_right. Full status-line themes such as Catppuccin fight with Oh my tmux's own theme, so use one or the other. General plugin advice: Plugins & TPM.

Update Oh my tmux

The README has no update section, but the setup makes it simple: your config file is a symlink into a git clone, so updating is a git pull in that clone, then a reload.

# Manual install in your home directory
$ git -C ~/.tmux pull
# Installed with install.sh (or the XDG manual steps above)
$ git -C ~/.local/share/tmux/oh-my-tmux pull
# Then reload, or press prefix r inside tmux
$ tmux source-file ~/.tmux.conf

Your .tmux.conf.local is a copy, so updates never change it, and new variables from the sample file do not appear in your copy. To see what changed, compare the two: diff ~/.tmux.conf.local ~/.tmux/.tmux.conf.local. Running the installer again also works, but it moves your current .tmux.conf.local to a timestamped backup and gives you a fresh copy.

Uninstall and restore your old config

Remove the symlink, the clone and your .local file, put your backup back, and restart the tmux server so none of the old settings linger:

$ rm ~/.tmux.conf ~/.tmux.conf.local
$ rm -rf ~/.tmux
$ tmux kill-server

$ rm ~/.config/tmux/tmux.conf ~/.config/tmux/tmux.conf.local
$ rm -rf ~/.local/share/tmux/oh-my-tmux
# Restore the backup the installer made (pick your timestamp)
$ ls -d ~/.tmux.conf.* ~/.config/tmux.* ~/.tmux.[0-9]* 2>/dev/null
$ mv ~/.tmux.conf.20261028175812.4242 ~/.tmux.conf
$ tmux kill-server

$ rm ~/.config/tmux/tmux.conf ~/.config/tmux/tmux.conf.local
$ rm -rf ~/.local/share/tmux/oh-my-tmux
$ tmux kill-server

tmux kill-server closes every session. To keep working while you switch, start a fresh server for the new setup with tmux -L clean and stop the old one later.

Troubleshooting

Something looks wrong and you are not sure it is Oh my tmux

Stop all tmux servers and start one with no config: tmux -f /dev/null -L test. If the problem is still there, it is tmux or your terminal (see troubleshooting); if not, it is the config.

A set or bind in .tmux.conf.local has no effect

Put it in the user customizations section and add #!important at the end of the line.

"tmux is currently running, please terminate the server"

The installer will not run inside tmux. Leave tmux (detach or exit) and run it from a plain terminal, or run it with PERMISSIVE=true and accept that existing sessions keep outdated environment variables.

"Do not execute this script as root!"

Run it as the user who will use tmux, without sudo.

Boxes or question marks instead of arrows

Your font lacks the Powerline symbols. Install a patched or Nerd Font and select it in your terminal, or set the four separator variables back to empty strings.

The status line is broken or duplicated at the bottom

The README blames a mismatch in character width tables (glib 2.50.1+ with glibc older than 2.26 on Linux, or iTerm2's "Use Unicode version 9 character widths" setting). Use a UTF-8 locale (LC_CTYPE) and avoid emoji in the status variables.

The mouse does not work

Oh my tmux leaves the mouse at tmux's default, which is off before tmux 3.8. Press Ctrl+b m, or add set -g mouse on to the user section.

High CPU on Windows

The config runs many shell commands, and forking is slow under Cygwin. The author recommends WSL with Windows Terminal; see tmux on Windows.

Oh my tmux vs your own config vs a theme plugin

Pick Oh my tmux if you want a complete, good-looking setup today and are happy to learn its keys. Write your own config if you want to know what every line does, keep tmux's standard keys (useful when you also work on servers with stock tmux), or run a recent tmux whose new defaults already cover most of what Oh my tmux adds: tmux 3.8 turns the mouse on and has built-in light and dark themes. A short config plus a theme plugin sits in between. Start from the config reference or the config generator.

Frequently asked questions

Something wrong or out of date on this page? Email hello@tmux.app and we will fix it.