Q: I don't like the way that iTerm2 renders bold fonts.

A: Go to Preferences->Profiles->Text and change the "Draw bold text in bold font" and "Draw bold text in bright colors" settings. Try running this command in bash to see the difference between the two behaviors:

printf '\e[0;31mplain\n\e[1;31mbold\n'\

Q: How can I improve iTerm2's performance?

A: Make sure you are running the latest version. Disable transparency and blur. Use a solid background color rather than an image.

Q: Why my arrow/HOME/END keys are not working?

A: When the terminal type of your sessions is set to one of those "xterm" types, iTerm2 handles the arrow keys, the home key, and the end key in a special way. The escape sequences generated by these keys depend on if your session is in the normal mode or the cursor application mode. For the normal mode, iTerm2 generates ESC [ sequences. For the cursor application mode, iTerm2 generates ESC O sequences.

These two modes are respected by many console programs. Most shells are good with the normal mode. Full screen applications such as vi and emacs usually use cursor application mode. Termcap and terminfo are written for full screen applications, so they will report the cursor application mode sequences.

In any case, if your keys are not working, first check if iTerm2 is set to correct terminal type. The terminal type set in the terminal profile should match the TERM variable in your session environment. Scripts like .bashrc may change the terminal type and create some problem. Secondly, check if there's any customized key bindings for these keys. These settings will override the default behavior. And lastly, check if you have set up your console application correctly. In some system, vi by default works in the original vi mode, which does not support arrow keys.

If everything else fails, you can fire up another terminal program that works for you, check the escape sequences generated by arrow keys in those program, and go back to iTerm2, type these key sequences in your keyboard profile.

Q: Where does iTerm2 store its settings?

A: Preferences, including profiles, are stored in ~/Library/Preferences/com.googlecode.iterm2.plist. To modify it, use the "defaults" command. For example, to delete all settings, run:

defaults delete com.googlecode.iterm2

Q: The fonts are looking weird. What should I do?

A: iTerm2 lets you to specify two fonts. If you only use English or western european languages, you probably only need to set the font for ASCII characters. For other languages, you need to specify a font that works with your language as the Non-ASCII font. You need to make sure the size (height) of two fonts do not differ greatly, so iTerm2 won't display a mess of mixed glyphs.

Q: Some characters appear to be twice as wide as others, and things aren't lining up correctly.

Q: I'm a Chinese, Japanese, or Korean user and some characters don't line up because they are not rendered in double-width.

A: Go to Preferences->Profiles->Text and change the setting of "Treat ambiguous-width characters as double-width."

Q: Why can't I set my session's shortcut key to Ctrl-Cmd-D?

A: That key is used by macOS's dictionary program.

Q: How do I make the option/alt key act like Meta or send escape codes?

A: Go to Preferences->Profiles tab. Select your profile on the left, and then open the Keyboard tab. At the bottom is a set of buttons that lets you select the behavior of the Option key. For most users, Esc+ will be the best choice.

Q: What modifier keys affect marking a selection for copy and paste?

A: If you hold down modifier keys while making a selection, the behavior changes in various ways:

  • Alt/Option: Mouse reporting will be disabled. If you're using vim and you can't make a selection, try holding down the alt key and see if that fixes it.
  • Alt + Cmd: Make a rectangular selection.
  • Shift: Extend an existing selection.
  • Alt + Shift: Extend a rectangular selection.
  • Cmd: Make a discontinuous selection

Additionally, you can affect other mouse-related activities with modifier keys:

  • Dragging a selection copies and pastes it. If you keep doing this by accident, turn on *Prefs > Advanced > To drag images or selected text, you must hold ⌘. This prevents accidental drags..
  • Cmd+click on a URL opens it.

Q: How do I change a tab's title?

A: Press Cmd-I (or View->Edit Current Session...) and enter a new title in the "Name" field. You can set it programmatically (in bash) with:

echo -e "\033];MY_NEW_TITLE\007"

Q: How do I set iTerm2 as the handler for ssh:// links?

A: Two steps:

  1. Create a new profile called "ssh". In the General tab, select the Command: button and enter $$ as the command.
  2. In Preferences->Profiles->General, select "ssh" for "Select URL Schemes...."

Q: How can I open a profile from the Profiles window in a new window without using the mouse?

A: Select a profile with the up and down arrow keys and press shift-enter.

Q: How do I get 256 color mode working in vim?

A: The recommended way is to set your terminal type to xterm-256color in Preferences->Profiles->Terminal->Report Terminal Type. You may also need to put set background=light or set background=dark in your .vimrc.

Q: Mouse reporting in vim doesn't work for some rows/columns in a big terminal window.

A: Older mouse reporting protocols didn't work in large terminals. Recent versions of vim (at least 7.4) support the "SGR" protocol, which does not have any practical limits on terminal size. To enable it in vim, add this to your .vimrc:

if has('mouse_sgr')
    set ttymouse=sgr

Q: How do I use Growl with iTerm2?

A: In bash:

echo $'\e]9;Growl Notification\007'

Q: How do I make the mouse work in emacs?

A: This is the simple but dumb way:

(require 'mwheel)
(require 'mouse)
(xterm-mouse-mode t)
(mouse-wheel-mode t)
(global-set-key [mouse-4] 'next-line)
(global-set-key [mouse-5] 'previous-line)

The rabbit hole goes deep.

Q: When I go full-screen on a two-screen system my menu bar disappears?

A: Do you have MegaZoomer installed? It intercepts cmd-Enter to make a window full-screen, and apparently has this side effect.

Q: Why is my text all black and white?

A: The most common cause is that "minimum contrast" (under preferences > profiles > colors) is turned up all the way.

Q: How can I make the tab bar visible in fullscreen mode?

A: Toggle Show Tabs in Fullscreen under the View menu (cmd-shift-T).

Q: When I use a third-party app like SizeUp or Spectacle to make an iTerm2 window fill the screen it doesn't quite fill it.

A: Turn on Preferences>Advanced>Terminal windows resize smoothly.

Q: Where is the source code?

A: See gnachman's Github iTerm2 project.

Q: How can I open iTerm2 to a directory from Finder?

A: iTerm2 Finder Tools is excellent.

Q: How can I keep the cursor guide always visible?

A: Turn on the Cursor Guide checkbox in Preferences>Profiles>Colors.

Q: How can I make the toolbelt open automatically?

A: Turn on the Open Toolbelt checkbox in Preferences>Profiles>Window.

Q: How can I prevent the window from resizing when I change the font with cmd-+ and cmd--?

A: Turn off Preferences>General>Adjust window when changing font size.

Q: tmux integeration and mosh don't play nice together

A: mosh is not a reliable transport. You have a few options if ssh is driving you nuts:

  1. Use a hacked version of mosh that is a reliable transport. Instructions on building it can be found on Donn Lee's home page.
  2. Use Eternal Terminal.