- Highlights for New Users
- General Usage
- Menu Items
- Touch Bar
- Copy Mode
- Profile Search Syntax
- Automatic Profile Switching
- Buried Sessions
- Captured Output
- Session Restoration
- Shell Integration
- Smart Selection
- Status Bar
- tmux Integration
- Scripting Fundamentals
- Python API
- Dynamic Profiles
- Inline Images Protocol
- Proprietary Escape Codes
iTerm2 > Show Tip of the Day
When you start using iTerm2 it will offer to show you a daily tip describing a feature. You can show a tip immediately by selecting this item.
iTerm2 > Check for Updates
Checks to see if a new version of iTerm2 is available. If Preferences > General > Prompt for test-release updates is turned on then this includes beta versions; otherwise only stable versions are downloaded.
iTerm2 > Toggle Debug Logging
This saves helpful debugging information in memory. When it is toggled off it is saved to /tmp/debuglog.txt.
iTerm2 > Copy Performance Stats
This copies information about drawing speed to the pasteboard. This is useful when reporting issues relating to poor performance.
iTerm2 > Capture GPU Frame
This saves information about how the current session is drawn. This is useful when reporting issues relating to drawing errors in the GPU renderer.
iTerm2 > Secure Keyboard Entry
When this is enabled, the operating system will prevent other programs running on your computer from being able to see what you are typing. If you're concerned that untrusted programs might try to steal your passwords, you can turn this on, but it may disable global hotkeys in other programs.
iTerm2 > Make iTerm2 Default Term
Makes iTerm2 the default terminal for opening .command, .tool, .zsh, .csh, and .pl files.
iTerm2 > Make Terminal Default Term
You must hold down Option for this entry to be visible. Makes Terminal.app the default terminal for opening .command, .tool, .zsh, .csh, and .pl files.
iTerm2 > Install Shell Integration
This opens a window that guides you through the installation of the Shell Integration features.
Shell > New Window/Tab
This creates a new window or tab with the default profile. If the current session is a tmux integration session, then you will be prompted for whether to create a local or tmux session.
Shell > New Tab with Current Profile
This creates a new tab using the same profile as the current session rather than the default profile.
Shell > Duplicate Tab
Creates another tab with the same arrangement of split panes, profile, etc.
Shell > Split Vertically/Horizontally
These menu items allow you to divide a tab into two or more split panes. The panes can be adjusted by dragging the line that divides them. They will use the default profile.
Shell > Split Vertically/Horizontally with Current Profile
These menu items allow you to divide a tab into two or more split panes. The panes can be adjusted by dragging the line that divides them. They will use the profile of the current session.
Shell > Save Selected Text
Saves the selected text to a file.
Shell > Close
Terminates the current session.
Shell > Close Terminal Window
Terminates all sessions in the current window.
Shell > Close All Panes in Tab
Terminates all sessions in the current tab.
Shell > Broadcast Input > ...
These options allow you to send keyboard input to more than one session. Be careful.
- Send input to current session only: The default setting.
- Broadcast to all panes in all tabs: Anything you type on the keyboard goes to all sessions in this window.
- Broadcast to all panes in current tab: Anything you type on the keyboard goes to all sessions in this tab.
- Toggle broadcast input to current session: Toggles whether this session receives broadcasted keystrokes within this window.
- Show Background Pattern Indicator: If selected, sessions receiving broadcast input get an obnoxious red-stripe background.
Shell > tmux > ...
These commands let you interact with the tmux integration
- Detach: Detaches from the tmux session associated with the current pane. It remains running in the tmux server.
- New tmux Window/Tab: Creates a new tmux window, which appears in either a native window or tab, as requested. 8 Dashboard: The tmux dashboard is a view that lets you see all your tmux sessions and windows at a glance, adjust which are visible, rename them, and change the current tmux session.
Edit > Undo Close Session/Tab/Window
After you close a session, tab, or window then you have five seconds to undo it. The amount of time is configurable in PReferences > Profiles > Session.
Edit > Copy (With Styles)
Hold down Option to turn Copy into Copy With Styles, which includes fonts and color information in the copied text.
Edit > Copy with Control Sequences
Copies the selected text, including control sequences that will reproduce the appearance (bold, colors, etc.) of the copied text when pasted into a terminal. Note that these will not be exactly the control sequences that were originally received, but instead a reconstruction that has the same effect.
Edit > Copy Mode
Enters Copy Mode which lets you make selections using the keyboard. See Copy Mode for details.
Edit > Paste Special > Advanced Paste
This opens the Advanced Paste window which lets you select a string from the pasteboard in recent history, select different representations of the current pasteboard, and modify the string before pasting it. You can modify it by appling a regex substitution, using various built-in modifiers (such as base-64 encoding), or edit it by hand.
Edit > Paste Special > Paste Selection
Pastes the currently selected text (which may differ from the text in the pasteboard).
Edit > Paste Special > Paste File Base64-Encoded
If there is a file on the pasteboard then this is enabled. When invoked, it base64-encodes the file and pastes the encoded value.
Edit > Paste Special > Paste Escaping Special Characters
"Paste Escaping Special Characters" pastes the current string in the clipboard, but places a backslash before spaces and backslashes.
Edit > Paste Special > Paste Slowly
"Paste Slowly" pastes the current string in the clipboard, but it doesn't send the whole string at once. It is sent in batches of 16 bytes with a 125ms delay between batches.
Edit > Paste Special > Paste Faster/Slower
Adjusts the speed of pasting to be faster or slower.
Edit > Paste Special > Paste Slowly Faster/Slower
Adjusts the speed of slow pasting to be faster or slower. You must hold down option for this menu item to be visible.
Edit > Paste Special > Warn Before Multi-Line Paste
When enabled, you'll be warned before pasting more than one line.
Edit > Paste Special > Limit Multi-Line Paste To Shell Prompt
If Warn Before Multi-Line Paste is on, then this restricts it to warn only when you're at the shell prompt. It only works if shell integration is installed, since otherwise iTerm2 cannot tell when you're at the shell prompt.
Edit > Paste Special > Warn Before Pasting One Line Ending in a Newline at Shell Prompt
This requires shell integration to be installed to work. If you try to paste one line that ends in a newline while at the shell prompt and this is enabled, you'll get a confirmation dialog before the text is pasted.
Edit > Snippets
Gives access to Snippets, which are saved bits of text that can be pasted quickly. You can change snippets in Prefs>Shortcuts>Snippets.
Edit > Actions
Gives access to Actions, which are user-defined actions similar to those that can be bound to a keystroke. You can change actions in Prefs>Shortcuts>Actions.
Edit > Selection Respects Soft Boundaries
When enabled, vertical lines of pipe characters
| will be interpreted as pane dividers (as in vim or emacs) and selection will wrap at them.
Edit > Select Output of Last Command
Requires shell integration to be installed. Selects the output of the last command.
Edit > Select Current Command
Requires shell integration to be installed. Selects the text of the current command entered at the command prompt.
Edit > Find > Find
Opens or focuses the find panel. Select the down arrow to the left of the search field to open the options menu, which lets you select case insensitivity and regular expression options. The default case sensitivity option of "Smart Case Sensitivity" performs a case-sensitive search if the search query contains any upper case letters. Otherwise, a case-insensitive search is performed.
Edit > Find > Find Next/Previous
Note that the direction of next and previous is reversed relative to the standard macOS search direction. If you prefer for Next to mean down and Previous to mean up, set Preferences>Advanced>Swap Find Next and Find Previous to No.
Edit > Find > Find Globally
Opens a window that lets you search all tabs at once.
Edit > Find > Find URLs
Searches the current session for URLish looking strings.
Edit > Marks and Annotations > Set Mark
Records the current scroll position. Use Edit > Jump to Mark to restore the scroll position.
Edit > Marks and Annotations > Add Annotation at Cursor
Adds an annotation to the word beginning at the cursor. An annotation is a scratchpad for you to write notes about a chunk of text in your history.
Edit > Marks and Annotations > Jump to Mark
Scrolls to the location of the last mark.
Edit > Marks and Annotations > Alerts > Alert on Next Mark
When a mark is set (typically by Shell Integration when the currently running shell command terminates) then show an alert.
Edit > Clear Buffer
Clears the entire terminal history and the mutable area.
Edit > Clear Scrollback Buffer
Clears scrollback history, preserving the mutable area.
View > Show Tabs in Fullscreen
If enabled, tabs are shown in fullscreen windows.
View > Toggle Full Screen
Enters or exists full screen mode. iTerm2 supports both the standard macoS full screen mode, where the window occupies its own Space, and its traditional full screen mode that shares a Space with other windows. You can control which is used in Preferences > General > Native full screen windows.
View > Use Transparency
This toggles transparency. It only has an effect if you have configured your session to be transparent under Preferences > Profiles > Window > Transparency. When Full Screen mode is entered, transparency is turned off by default, but you can select this menu item to re-enable it.
View > Zoom In on Selection
When a selection is present this is enabled. Zooming on a selection removes all other text from the session and lets you focus on just the zoomed-in-on text. Pressing escape will invoke Zoom Out when you are in the Zoom In state.
View > Zoom Out
Exits the Zoom In on Selection mode.
View > Find Cursor
Reveals the current cursor position.
View > Show Cursor Guide
Toggles the visiblity of the cursor guide which is a horizontal rule showing the location of the cursor.
View > Show Timestamps
Indicate the time of last modification of each line on the screen.
View > Show Annotations
Toggles the visibility of annotations.
View > Composer
Opens a view that lets you edit a command before sending it.
View > Auto Command Completion
Automatically shows a window with command completion suggestions as you type. Only usable when you have command history built up with Shell Integration.
View > Open Quickly
If you have lots of sessions you can quickly find the one you're looking for with Open Quickly. Select the View > Open Quickly menu item (cmd-shift-O) and then enter a search query. You can search by tab title, command name, host name, user name, profile name, directory name, badge label, and more. Queries are scored according to relevance and sorted by score. Open Quickly also lets you create new tabs, change the current session's profile, open arrangements, and change the color preset. If you start your query with a / then that gives you a shortcut to various commands. /a followed by an arrangement name restores the arrangement. /f restricts the query to existing sessions, excluding options to open new tabs, etc. /p restrics the query to profile names to switch the current session to. /t restricts the results to "open new tab" for matching profile names. /c restricts the results to color presets.
View > Maximize Active Pane
When there are split panes present, this toggles whether a given pane expands to fill the tab. When a maximized pane is present, the tab will be inscribed with a dotted outline.
View > Size Changes Update Profile
When enabled, changes made to the text size in this session (by selecting Make Text Bigger/Smaller) will be reflected in its profile.
View > Start Instant Replay
Stepping through time allows you to see what was on the screen at a previous time. This is different than going back through the scrollback buffer, as interactive programs sometimes overwrite the screen contents without having them scroll back. Once in this mode, you can use the left and right arrow keys to step back and forward, respectively. The "esc" key exits this mode, as does clicking the close button in the bar that appears on the bottom. You can adjust the amount of memory dedicated to this feature in Preferences > Instant Replay uses xx MB per session. The more memory you assign, the further back in time you can step. The instant replay UI also lets you choose to export a section of your terminal history to share with other iTerm2 users.
View > Tab Color
Allows you to select a tint color for the tab, to make it easier to distinguish. You can also change the tab color in Profiles > Preferences > Colors.
Session > Edit Session
This opens a window that lets you change the settings of the current session without affecting any other sessions. Changes made in this panel will not be overridden by subsequent changes to the profile. Settings not cahnged in this panel will be affected by changes to the profile.
Session > Run/Stop Coprocess
Allows you to start and stop a coprocess linked to the current session. Learn more about coprocesses.
Session > Restart Session
After a session ends (e.g., because the shell exits) this menu item becomes enabled. It will re-run your profile's command in the same viewport as the terminated session.
Session > Open Autocomplete...
Shows the autocomplete window, which offers to finish typing a word that you've begun. Learn more about autocomplete on highlights page.
Session > Open Command History...
If you use Shell Integration then Open Command History presents a list of recently used commands to select from.
Session > Open Recent Directories...
If you use Shell Integration then Open Recent Directories presents a list of recently used directories to select from.
Session > Open Paste History...
"Open Paste History" opens a window showing up to the last 20 values that were copied or pasted in iTerm2. You can search its contents by typing a (non-necessarily-consecutive) subsequence of characters that appear in the value. You can use arrow keys and enter to make a selection, or you can click on an item to choose it, and it will be pasted. If you enable the Save copy/pate history to disk preference then these values will persist across sessions of iTerm2.
Adds a trigger, defaulting to highlighting the currently selected text.
Session > Reset
Resets the internal state of the emulator and clears the screen. Use this if you get wedged in a bad state, like the wrong character set or mouse reporting mode is stuck.
Session > Log > Start/Stop
Logging saves all input received in a session to a file on disk.
Session > Log > Import/Export Recording...
The Instant Replay feature allows you to view the past window state. The import/export feature allows you to save that state to an
itr file and share it with others. For more control, enter instant replay by selecting View > Start Instant Replay and click the Export button there; it will allow you to clip the recording by selecting its start and end points separately.
Session > Terminal State
Shows the internal state of the terminal emulator and lets you directly manipulate it.
Session > Bury Session/Buried Sessions
Buries or unburies a session. See Buried Sessions for details.
If you have scripts located in
$HOME/Library/Application Support/iTerm2/Scripts they'll be added to this menu.
Scripts in the
AutoLaunch folder will be run when iTerm2 starts.
The Manage submenu contains items to help you create and maintain Python scripts that use iTerm2's Python API.
New Python Script
Use this to create a new script. See the Python API Tutorial for details on how to use it.
Open Python REPL
Creates a window with a Python read-eval-print loop (REPL). This is meant for experimenting with iTerm2's Python API. You may be asked to download and install the Python Runtime before this window will open. See the REPL section of the tutorial for details.
This opens a window that lets you modify the dependencies and Python version of scripts using iTerm2's Python API. You can add or remove dependencies using pip3 through this UI, which is recommended because each script may have its own copy of the Python environment it uses.
Check for Updated Runtime
Checks if a new version of the Python Runtime is available. It may contain bug fixes or new APIs.
Reveal Scripts in Finder
Scripts folder in Finder.
Allows you to choose an exported script (with the
its extension) to install.
Allows you to export an existing script as an
its file, suitable for sharing. If you have a code signing certificate and private key, you can opt to sign your exported script. Signed scripts are easier to install.
The console shows the running scripts, their logs, and the history of communication between the script and iTerm2. It also offers access to the Inspector, which lets you view variables in the various sessions, tabs, and windows. It also reveals registered functions. Both the console and the inspector are intended to be used as debugging tools for people working with scripts using iTerm2's Python API.
This menu contains a list of profiles. Selecting one opens it in a new tab. Hold option while selecting a profile to open it in a new window, instead.
Profiles > Open Profiles...
This opens the "Profiles Window" which allows you to create new windows, tabs, or panes from one or more profiles. You can perform a search by entering text in the search field. Profile names and tags are searched, and the listed profiles are filtered as you type. You can use the up and down arrow keys to make a selection. Pressing enter will open a new tab, while shift-enter will open a new window. You can make multiple selections by holding down shift or cmd and clicking on profiles. The "New Tabs in New Window" button is enabled only when more than one profile is selected: it will open a new window and create a new tab for each profile selected.
Profiles > Open All
Opens all profiles in tabs (or in windows, if Option is pressed).
Toolbelt > Set Default Width
Saves the current window's toolbelt width as the default width for new windows' toolbelts.
Toolbelt > Actions
This toggles the visibility of the Actions tools. It has a list of user-defined actions (for example, send a canned string of text). The tool provides an interface for editing the actions as well as invoking them.
Tolbelt > Captured Output
This toggles the visibilty of the Captured Output tool. It shows captured output located with the Capture Output trigger. See Captured Output for more information.
Toolbelt > Command History
This toggles the visibility of the Command History tool. It shows recently used commands. You must install Shell Integration for this to know your command history.
Toolbelt > Show Toolbelt
This toggles the visibility of the Toolbelt on the right side of all windows.
Toolbelt > Jobs
This toggles the visibility of the Jobs tool, which shows the running jobs in the current session, and allows you to send them signals.
Toolbelt > Notes
This toggles the visibility of the Notes tool, which provides a freeform scratchpad in the toolbelt.
Toolbelt > Paste History
This toggles the visibility of the Paste History tool, which shows recently pasted strings in the toolbelt.
Toolbelt > Profiles
This toggles the visibility of the Profiles tool, which lets you select profiles to open new windows, tabs, and split panes.
Toolbelt > Recent Directories
This toggles the visibility of the Recent Directories tool. It shows recently used directories sorted by a combination of recency and frequency of use. You must install Shell Integration for this to know your directory history. You can right click a directory to open a context menu that allows you to "start" a directory. This keeps it pinned at the bottom of the list so it's easy to find.
Toolbelt > Snippets
This toggles the snippets tool, which holds strings that can be pasted quickly. You can edit snippets in Prefs>Shortcuts>Snippets.
Window > Save/Restore Window Arrangement
The current state and positions of windows, tabs, and spit panes is recorded and saved to disk with Save Window Arrangement. Restore Window Arrangement opens a new collection of windows having the saved state. You can automatically restore the arrangement in Preferences > General > Open saved window arrangement.
Window > Restore Window Arrangement as Tabs
Restores the windows in the selected window arrangement as tabs in the current window.
Window > Password Manager
Opens the password manager.
Window > Edit Tab Title
Allows you to enter a tab title to override the default, which is the current session's title. This is an interpolated string.
Window > Edit Window Title
Allows you to enter a window title to override the default, which is the current tab's title. This is an interpolated string.
Window > Window Style
Allows you to modify the window style, for example by removing the title bar.