GeekCoding101 make your way to geek

iTerm2, tmux, Oh My Zsh & Powerlevel10k Setup on Mac

Set up a Mac terminal step by step: iTerm2, Nerd Fonts, Oh My Zsh with Powerlevel10k, and tmux via gpakosz/.tmux, plus tmux auto-attach on launch.

7 min read
Crafting A Productivity Environment With Iterm Tmux And Beyond 1
On this pageThe setup at a glance

To get a productive terminal on a Mac:

  1. Install iTerm2.
  2. Add a Nerd Font.
  3. Switch your shell to Oh My Zsh with the Powerlevel10k theme.
  4. Run everything inside tmux with a ready-made config.

This post walks through each step with the exact commands I use. It ends with a small script that drops every new iTerm2 window into the same tmux session.

A decade or so ago I spent my whole working day in a Linux terminal: moving files around, writing code in Vim, maintaining services, reading kernel dumps, and jumping between tmux sessions. I rarely needed a GUI. On the Mac I wanted that same feel back, so here is how I rebuilt it.

The setup at a glance

PieceWhat it doesWhere to get it
iTerm2Replacement for macOS Terminal (split panes, profiles, better colors)https://iterm2.com/
Nerd FontPatched font with icons that Powerlevel10k and the tmux status bar useInstalled by the Powerlevel10k wizard
Oh My ZshFramework to manage your zsh config, themes and pluginshttps://github.com/ohmyzsh/ohmyzsh
Powerlevel10kzsh theme with a fast, configurable prompthttps://github.com/romkatv/powerlevel10k
tmuxTerminal multiplexer: many sessions and windows, detach and reattachHomebrew (brew install tmux)
gpakosz/.tmuxSelf-contained, pretty tmux configurationhttps://github.com/gpakosz/.tmux
Default macOS Terminal window right after logging in, plain white background with a basic prompt

Step 1: Install iTerm2

iTerm2 is a replacement for Terminal and the successor to iTerm. If you spend a lot of time in a terminal, its many small features add up. It is free software, and the source code is on GitHub.

Download it from https://iterm2.com/ and install it. If you use Homebrew, you can run this instead:

Terminal window
brew install --cask iterm2
Freshly installed iTerm2 window with its default black theme and prompt

Out of the box it still looks plain, but you now have all of iTerm2’s advanced features. This post is not about those features, so explore them on the official site. Next comes the customization.

Step 2: Know about Nerd Fonts

Before customizing anything, you need a Nerd Font. Powerlevel10k uses one, and its setup wizard will offer to install it for you in Step 4.

Nerd Fonts are regular programming fonts patched with extra glyphs: icons for Git, folders, languages, tools and separators. Because the icons live inside the font, every app using that font can show them. You don’t need a separate icon library or a tool-specific extension. The result is one consistent look across your prompt, tmux and editor.

Step 3: Customize iTerm2

iTerm2 Preferences General Selection tab with clipboard access and smart selection options highlighted iTerm2 Profiles Text settings with underline cursor, Powerline glyphs and MesloLGM Nerd Font Mono selected

If you like, set a favorite character as the background image: iTerm2 window with a favorite character image set as the terminal background

Before and after: iTerm2 window after customization, showing the new background image and styled prompt

Step 4: Oh My Zsh and Powerlevel10k

Install Oh My Zsh, which manages your zsh configuration:

Terminal window
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
Terminal output of the Oh My Zsh installer finishing successfully

Clone Powerlevel10k into Oh My Zsh’s custom themes folder:

Terminal window
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Turn it on. I source the theme file directly from ~/.zshrc:

Terminal window
echo "source ~/.oh-my-zsh/custom/themes/powerlevel10k/powerlevel10k.zsh-theme" >> ~/.zshrc

The Oh My Zsh way also works. Set ZSH_THEME="powerlevel10k/powerlevel10k" in ~/.zshrc instead. Use one method, not both.

Restart zsh:

Terminal window
exec zsh

The Powerlevel10k configuration wizard starts: Powerlevel10k configuration wizard first screen asking whether the prompt icons render correctly

Let it install the fonts, then answer the questions and pick whatever style you like. You can rerun the wizard any time with p10k configure. iTerm2 with Powerlevel10k applied: a Powerline prompt showing the current folder and git branch, with a cartoon character as background

Much better, but not quite what I wanted. Next comes tmux.

Step 5: tmux with gpakosz/.tmux

tmux is a terminal multiplexer. It lets you:

  • switch easily between several programs in one terminal,
  • detach them so they keep running in the background,
  • reattach them to a different terminal.

macOS does not ship tmux, so install it first. Then type tmux to check it runs:

Terminal window
brew install tmux
tmux
Default tmux session with a plain green status bar at the bottom of the terminal

Install the config

I use gpakosz/.tmux, a self-contained, pretty and versatile .tmux.conf. Note that rm -fr .tmux deletes any existing ~/.tmux folder, so back it up first if you have one.

Terminal window
cd ~
rm -fr .tmux
git clone https://github.com/gpakosz/.tmux.git
ln -s -f .tmux/.tmux.conf
cp .tmux/.tmux.conf.local .

Keep your own changes in ~/.tmux.conf.local, never in .tmux.conf. That way you can update the main config with a git pull without losing anything.

My additions

Add these lines to ~/.tmux.conf.local, above the line # -- custom variables:

Terminal window
# increase history size
set -g history-limit 9999999
# start with mouse mode enabled
set -g mouse on
# Ctrl+Shift+Left/Right moves the current window left/right
bind-key -n C-S-Left swap-window -t -1\; select-window -t -1
bind-key -n C-S-Right swap-window -t +1\; select-window -t +1

history-limit sets the scrollback kept per pane. A very large value uses more memory in long-running sessions, so lower it if that matters to you.

Vi mode

I’m a Vi/Vim fan, so I enable vi keys in ~/.tmux.conf.local:

Terminal window
set -g status-keys vi
set -g mode-keys vi
Lines in .tmux.conf.local that enable Vi mode key bindings

Status bar colors and separators

Set the right-hand status bar colors:

Terminal window
tmux_conf_theme_status_right_fg="$tmux_conf_theme_colour_12,$tmux_conf_theme_colour_14,$tmux_conf_theme_colour_6"
tmux_conf_theme_status_right_bg="$tmux_conf_theme_colour_15,$tmux_conf_theme_colour_17,$tmux_conf_theme_colour_9"
tmux status bar color settings in .tmux.conf.local using theme colour variables

Then find the powerline-style separator lines in ~/.tmux.conf.local and uncomment them. These separators need the Nerd Font from Step 4.

Terminal window
tmux_conf_theme_left_separator_main='\uE0B0'
tmux_conf_theme_left_separator_sub='\uE0B1'
tmux_conf_theme_right_separator_main='\uE0B2'
tmux_conf_theme_right_separator_sub='\uE0B3'
tmux separator settings in .tmux.conf.local using Powerline glyph codes

Set an icon for the left status: tmux configuration line that sets an icon for the left side of the status bar

Reload

Terminal window
tmux source ~/.tmux.conf
Customized tmux session in iTerm2 with a Powerline-style status bar and the Powerlevel10k prompt

Auto-attach tmux when iTerm2 starts

This script attaches to a session called kongfu, or creates it if it doesn’t exist. If the session is already attached in another window, it prints a notice instead of attaching twice.

#!/bin/zsh
tmux ls | grep kongfu | grep -q attached
if [[ $? != 0 ]]; then
tmux attach -t kongfu || tmux new-session -s kongfu
else
echo "********************************************************************************"
echo "* Ignore attaching tmux kongfu session as it has been attached already. *"
echo "********************************************************************************"
fi

Set it up in three steps:

  1. Save the script as ~/bin/tmux_init.sh.

  2. Make it executable:

    Terminal window
    chmod 755 ~/bin/tmux_init.sh
  3. Set it as the startup command in iTerm2’s default profile: iTerm2 Default profile General tab with ~/bin/tmux_init.sh set as the Send text at start command

Want to rebuild a whole multi-window tmux layout, services included? See my post Crafting A Bash Script with Tmux.

Step 6: Fix Powerlevel10k colors for Anaconda and Node.js

I use Anaconda and Node.js environments, and I didn’t like the default colors Powerlevel10k gives their prompt segments.

Open ~/.p10k.zsh and find the Anaconda and Node.js version segment settings. Change their colors: Powerlevel10k config lines setting the Anaconda segment foreground to 0 and background to orange1

Powerlevel10k config lines setting the Node.js version segment foreground to 7 and background to green4 Powerlevel10k right prompt elements list in .p10k.zsh with the node_version entry highlighted

Then reload:

Terminal window
source ~/.p10k.zsh

Show time

Here is a recording of the finished setup in my environment:

https://www.youtube.com/watch?v=TBfvoSeyP4U

If the integrated terminal in VS Code shows broken icons after this setup, see Fix Font in VSCode Terminal.

FAQ

Does macOS come with tmux? No. Install it with Homebrew (brew install tmux) or another package manager before following Step 5.

Do I need a Nerd Font for Powerlevel10k? Yes, if you want the icons and powerline separators. Without one you’ll see empty boxes or question marks. The p10k configure wizard can install a suitable font for you.

How do I rerun the Powerlevel10k setup? Run p10k configure. It rewrites ~/.p10k.zsh, so redo any manual edits, like the Anaconda and Node.js colors, afterwards.

Where should I put my own tmux settings with gpakosz/.tmux? In ~/.tmux.conf.local. The main .tmux.conf is meant to stay untouched so you can update it from the repo.

Why does a new iTerm2 window show a message instead of tmux? The startup script found the kongfu session already attached in another window. It skips attaching a second time on purpose. Detach the other window, or start a separate session with tmux new -s <name>.

Thanks for reading my blog post! Feel free to check out my other posts or contact me via the social links in the footer.

Keep reading

All posts