Table of Contents

Preferences

General

Startup

Window restoration policy

This setting determines how windows will be opened when iTerm2 is launched. Most users will want Use System Window Restoration Setting as it works best with Session Restoration. Users who exclusively use the Hotkey Window may prefer Only Restore Hotkey Window, which will not restore regular windows but will restore the hotkey window. If you have a default window arrangement saved then Open Default Window Arrangement will be available.

Open profiles window

If selected, the Profiles Window will automatically open when iTerm2 is started.

Restore windows to same Spaces

macOS apps do not typically restore windows to the same Space (aka Desktop) that they were originally on except on system restart. When this setting is enabled, iTerm2 will attempt to restore windows to their original Spaces.

Always open at least one terminal window at startup

If you have a hotkey window defined then iTerm2 won't open a regular window on launch. If you'd prefer to always have a visible window in addition to the hotkey window, enable this setting.

Closing

Quit when all windows are closed

If selected, iTerm2 will automatically quit when its last terminal window is closed.

Confirm closing multiple sessions

If selected, commands that close one session will not be confirmed, but commands that close multiple sessions (such as clicking the red button on a window with two or more tabs) will be confirmed with an alert box.

Confirm Quit iTerm2 Command

If selected, the Quit iTerm2 (cmd-Q) command will be confirmed if any terminal windows are open.

Even if there are no windows

Modifies Confirm Quit iTerm2 COmmand to disable the prompt when there are no open windows.

Disable all confirmations on system shutdown, restart, and log out

When enabled, iTerm2 will never block system shutdown, restart, and log out by asking for confirmation. Enabling this setting could cause you to lose work.

Magic

Add Bonjour hosts to profiles

If selected, all Bonjour hosts on the local network have a profile created for them as long as they're around.

Instant Replay Uses X MB per Session

This setting specifies the maximum amount of memory allocated to instant replay for each tab or split pane. More memory means instant replay is able to go farther back into the past. You can enter instant replay with View > Step Back in Time.

Save copy/paste and command history to disk

If selected, every time text is copied or pasted in iTerm2 it will be saved to disk. The last 20 values are recorded. They can be accessed with Edit > Open Paste History.... If you use Shell Integration then when this is enabled your command history, directory history, and remote hostname and usernames will also be saved to disk. Unchecking this will erase all of the saved information.

Enable Python API

Toggles the availability of the Python API. See Python API Authentication for details on the security model.

Custom Python API Scripts Folder

Normally Python API scripts go in ~/Library/Application Support/iTerm2/Scripts but if you'd prefer to have them elsewhere you can specify the path with this setting.

GPU Rendering

The GPU renderer improves drawing performance, but it may use more energy. You can also configure when it is enabled in Advanced GPU Settings.

The advanced settings are:

  • Disable GPU renderer when disconnected from power - Use this to conserve energy when not plugged in and to get the best drawing performance when connected to power.
  • Prefer integrated to discrete GPU - If your machine has two GPUs, enable this to use the slower but less power-hungry GPU.

Maximize throughput at the cost of higher latency

When this is enabled:

  • The frame rate will be reduced when a lot of data is being received.
  • Input handling is prioritized over redrawing, reducing the maximum frame rate.

You probably need to disable this to hit 120 FPS.

Compress scrollback history in the background

When enabled, scrollback history gets compressed when the app is idle. This causes slightly higher CPU utilization when the app is not in use but can significantly reduce memory usage when there are large scrollback buffers.

AI > General

Plugin

To use AI features you must install the AI plugin.

Consent

You must consent to AI features before they can be used. This is a secure user default which requires you to enter an administrator password to change.

API Key

Because AI features depend on your provider's API, users must provide their own API keys. Unlike most settings (which are saved in user defaults), the AI key is stored in the keychain to prevent unauthorized access.

AI Model

Selects the model used for AI features. The menu lists the models iTerm2 knows about, including any you have configured manually.

Manage AI Models…

Opens the Manual AI Models panel where you can add, edit, duplicate, and delete models. You can mark one model as the default and another as the economy model (a cheaper model used for frequent background jobs, such as command safety checks). See Manual AI Models below for the per-model fields.

Automatically update available AI models from live online database

When enabled, iTerm2 periodically refreshes the list of available models from an online database so newly released models appear without waiting for a software update. This is on by default.

Zero Data Retention

Turn this on if your OpenAI organization has Zero Data Retention enabled. iTerm2 then stops sending previous_response_id and sets store=false so that no response state is retained on the server. Leave it off otherwise, since it disables some optimizations.

Use AI to check safety of commands before running them

When enabled, iTerm2 checks a command with AI before it is run automatically. Deterministic rules run first, and a low-cost model is consulted only when those rules are inconclusive: either the economy model or, if you use on-device Apple Intelligence for this, Apple Intelligence. This is opt-in and off by default.

Timeout

The maximum time to wait for a response to an AI query.

AI > General > Manual AI Models

Reached through the Manage AI Models… button. This panel lists your manually configured models and lets you add, edit, duplicate, or delete them. A starred model is the default and another may be marked as the economy model. Each model has the following fields, edited in the add/edit sheet:

Model

The name of the model to use. This value is sent in the API request.

Token Limit

Gives the maximum number of tokens in the context and in a response. If this value is too high your requests may fail.

URL

The URL of the endpoint to send requests to.

API

Which style API to use.

Features

The following features are available. Not all APIs support all features.

  • Hosted File Search - OpenAI Responses API only
  • Hosted Web Search - OpenAI Responses API only
  • Function Calling - Most APIs support this
  • Streaming Responses - Most APIs support this
  • Code Interpreter - OpenAI Responses API Only
  • File Upload and Vector Store -OpenAI Responses API only. Vector store is not currently used.

Supports temperature

Enable this if the model accepts a temperature parameter. Some models reject requests that include one.

Configurable thinking

Enable this if the model supports a configurable thinking (reasoning) effort.

AI > General > Prompts

Here you can edit the prompts. Values in \(...) are substituted. The exact substitutions depend on which prompt it is. For more information on interpolated strings, see Variables.

  • Edit > Engage Artificial Intelligence - This prompt is sent when you select the Engage Artificial Intelligence menu item. ai.prompt is replaced with the text at the cursor or the manually entered prompt.
  • AI Chat + (options) - These prompts are used depending on which permissions are enabled.

AI > Features

Check Terminal State

This exposes information about the linked terminal to AI, including the current directory, user shell, the current or last command and its exit status, the size of the terminal window, the host you are SSHed to (if any), and the current username.

Run Commands

This makes functions available to AI that let it execute commands on your behalf.

Control Terminal

This makes functions available to AI that let it send keystrokes to the terminal. It also lets AI restart a session.

View Contents

This exposes the contents of the linked session to AI, including your command history. When it is set to provide contents automatically, a session-bound chat also includes the terminal's visible screen with each message you send.

View Manpages

This lets AI view manpages. If you are using ssh integration, man pages from the remote host may be viewed by it.

Write to Clipboard

This makes functions available to AI that let it write to the clipboard.

Write to filesystem

This makes functions available to AI that let it write to the filesystem.

Act in Web Browser

This makes functions available to AI that let it view the contents of the current web page (applicable only in browser profiles).

Offer AI command suggestion in Composer and Auto Composer

When enabled, as you type in the composer what you have entered and relevant files or commands are sent to AI so it can make suggested completions. This is disabled by default because it is not very privacy-friendly.

Software Update

Update to Beta test releases

If enabled, iTerm2 will periodically check if a new unstable version of iTerm2 exists, and if so it will prompt you to download and upgrade.

Check for updates automatically

If enabled, iTerm2 will periodically check if a new version of iTerm2 exists, and if so it will prompt you to download and upgrade.

Ignore non-critical shell integration updates

If enabled, you won't be notified of updates to shell integration unless there is a security problem or other critical issue. Shell integration update notificationss are shown when the shell integration script is loaded (when you log in or ssh somewhere that has it installed).

Notify only for cricial shell integration updates

When disabled, iTerm2 will let you know whenever your shell integration scripts are out of date. When enabled, it will warn you only when a very important update is available (e.g., because of a security issue).

Selection

Copy to clipboard on selection

If enabled, text is copied to the clipboard immediately upon selection. If not selected, you must select Edit > Copy to copy it.

Copied text includes trailing newline

If enabled, a terminal newline will be copied to the pasteboard when the selection includes one; otherwise, no selection will ever include a terminal newline.

Applications in terminal may access clipboard

If enabled, clipboard access will be granted via escape code to programs running in iTerm2. They will be able to set the contents of the system pasteboard. For more details, see Shell Integration Utilities.

Allow sending of clipboard contents?

An app running in the terminal can request that the terminal transmit the clipboard contents to it. Since this is a security risk, it normally requires you to consent each time.

Triple-click selects full wrapped lines

If enabled, a triple click selects a whole line, even if it was longer than one row in the terminal. If off, then triple click selects exactly one row.

Double-click performs smart selection

If enabled, double click performs smart selection instead of word selection as is standard on macOS.

Automatically enter copy mode on Shift+Arrow Key with selection

If enabled, pressing shift-left or shift-right will enter copy mode when a selection exists.

Characters considered part of a word for selection

When you double-click in the terminal window, a "word" is selected. The OS's algorithm for word selection is used, but it's extended to also include characters in this set. For example, by adding / to this field, double-clicking on a path/like/this would select the entire path instead of just one component.

Clicking on a command selects it to restrict Find and Filter

When enabled, clicking on a command dims other commands and then Find, Filter, and Select All operate only on the selected command. This requires shell integration.

When pasting a dropped filename, wrap it in double quotes

When enabled, dropping a file into a terminal will ensure that its name is always quoted with ".

Window

Smart window placement

If enabled, new windows will be opened where they least overlap existing windows.

Remember the size and position of previously closed windows

When enabled, new windows use the size and position of recently closed windows. Window frames are now remembered per profile rather than globally, so a new window opens where the last window using its profile was.

Adjust window when changing font size

If enabled, a change to a session's font will cause the window to grow or shrink.

Zoom maximizes vertically only

If enabled, the green "Zoom" button expands a terminal window vertically but does not affect its width. This can be overridden by holding down shift while clicking the zoom button.

Native full screen windows

If enabled, fullscreen windows will animate into a special desktop, as is typical in macOS 10.7 and later. If disabled, fullscreen windows will instantly go fullscreen without changing desktops.

Each tab may have its own window title

The OSC 0 and OSC 2 control sequences set the window title. This setting controls whether such a control sequence changes the window title associated with all sessions in the window, or only with the one in which it was received.

Settings

Load settings from a custom folder or URL:

If enabled, iTerm2 will load its settings from the specified folder or URL. After setting this, you'll be prompted when you quit iTerm2 if you'd like to save changes to the folder. Besides settings, iTerm2 can also sync your snippets, global notes, and session icon customizations through the folder. The first time this happens you'll be asked to consent, and if the same data was changed on more than one machine you'll be asked how to resolve the conflict.

Save changes to folder when iTerm2 quits

When you've turned on Load settings from a custom folder and this is on then any changes you make to your settings will be written to the custom folder.

Export/Import All Settings and Data

If you need to back up/restore all of your settings, such as when moving to a new computer, use these buttons. The following are included:

  • Python API Runtimes
  • Secure user defaults (settings that require your password to change)
  • Everything in the Settings window
  • The contents ~/.iterm2, such as shell integration scripts.
  • The contents of ~/Library/Application Support/iTerm2 which has your toolbelt notes, dynamic profiles, and more.
  • Python API scripts

Erase All Settings and Data…

Offers to export your settings and data first, then erases everything: your preferences, profiles, saved sessions, scripts, and the contents of ~/.iterm2 and ~/Library/Application Support/iTerm2. iTerm2 quits immediately afterward. Items stored in the macOS Keychain (such as the AI API key and Password Manager entries) are not erased.

tmux

When attaching, restore windows as…

The first dropdown box in the tmux Integration section allows you to define how tmux windows should be mapped to native constructs. When attaching to a new tmux session with the tmux integration, tmux windows not seen by iTerm2 before will open in either new windows or tabs, as specified by this preference.

Automatically bury the tmux client session after connecting

When the tmux integration is entered by running tmux -CC, the window in which that command was run will be buried.

Use "tmux" profile rather than profile of connecting session

This used to on by default, but is no longer so as of version 3.3. When enabled, a copy of the Default profile is created, called tmux. When using tmux integration all tmux sessions will use this profile.

When disabled, the profile of the session in which you ran tmux -CC will be used for all tmux sessions.

Status bar shows tmux status bar content, not native components.

When enabled, the status bar will contain the same content as the tmux status bar in its text-mode UI. When disabled, the status bar defined in the profile used for a tmux integration session will be used.

Pause a pane if it would take more than X seconds to catch up.

When both a tmux integration and tmux text-mode UI client are attached to the same tmux session, the text-mode UI can sink data much faster than tmux integration can because it drops information between frames. In this case, a large buffer can grow in the tmux integration window. Once the time to catch up exceeds this number of seconds, the tmux integration session will be paused. That means it stops receiving new data. While paused, no more data will be added to its buffer and may be lost forever. You will be prompted by a notification at the top of the window to unpause the session. This feature is only available in tmux 3.2 and later.

Warn Before Pausing

If enabled, a notification is shown when a pause is projected to occur within half of the pause deadline. See Pause a pane if it would take more than X seconds to catch up for more detail on pausing.

Unpause Automatically

When enabled, this unpauses the tmux session as quickly as possible after it is paused by tmux. It does not completely eliminate the possibility of data loss.

Mirror tmux paste buffer to local clipboard

tmux has a "paste buffer" which acts like its clipboard. When this option is enabled, the contents of the tmux paste buffer and copied into the system clipboard.

Experimental

Enable support for right-to-left scripts

When enabled, right-to-left scripts such as Arabic and Persian are reordered for display (bidi reordering) and their letters are joined in cursive form, instead of being drawn as plain left-to-right text. This is on by default.

Use SSH integration for ssh: URLs

If enabled, use SSH integration when opening an SSH URL.