iTerm2: A macOS Terminal Replacement With tmux Integration, Shell Integration and a Python API

The problem iTerm2 solves for macOS users

The default macOS Terminal.app is a thin wrapper around a shell. iTerm2 targets people who live in a terminal all day and want the emulator itself to carry state: which host you are on, which directory you came from, what a command printed five minutes ago. The README describes it as a "macOS Terminal Replacement" and lists features that are not part of a stock terminal, such as tmux integration, shell integration, inline images, automatic profile switching and a Python scripting API.

The audience is narrow on purpose. This is a macOS application. The README's platform badge says macOS, and the installation section describes downloading a signed app or building with Xcode. If your team runs Linux workstations, iTerm2 is not a candidate, and the RELATED searches list includes "iTerm2 Linux" precisely because people keep asking. The repository layout supports the same reading: the build is driven by iTerm2.xcodeproj and a Makefile that calls xcodebuild.

Where it earns its keep is the combination of session persistence and shell awareness. Sessions run in long-lived server processes, so a crash or an app upgrade does not kill your shells. Shell integration adds marks at each prompt, per-host command history and recent directories by "frecency". Those two features together change how you move around a fleet of SSH hosts.

How session restoration, tmux control mode and the Python API fit together

The architecture visible in the README has three layers worth separating.

The first is the session server. Shells are not children of the GUI process. They live in long-lived server processes, and iTerm2 reconnects to them after a crash or an upgrade. That is why session restoration is described as reconnecting "exactly where you left off" rather than replaying a scrollback buffer.

The second is tmux integration. Run tmux -CC and tmux windows become real macOS windows instead of a text-mode multiplexer inside one pane. The README states that sessions persist through crashes, SSH disconnects and app upgrades, and that two people can attach to the same session. If you already use tmux, this is the feature that decides whether iTerm2 is worth it: you keep tmux's server-side persistence and get native window management on top.

The third is the Python API. The repository contains an api/ directory, and the README advertises custom status bar components, triggers, menu items and "entirely new features" written in Python. Triggers are regex patterns that fire actions when matched: highlight text, run commands, send notifications, open a password manager, set marks, or invoke Python scripts. That is the extension surface. Anything you build there is tied to iTerm2; there is no portable plugin format described in the README.

Installing iTerm2 on macOS and running a first tmux session

The README gives two paths. The download path is the official one: get the latest version from iterm2.com/downloads, or try the nightly build at iterm2.com/nightly/latest. The nightly is described as the bleeding edge without building, and the README warns that development builds may be less stable than official releases.

The source path starts with a clone. There are no manual prerequisites, because make setup installs Homebrew, Xcode, Rust and the rest, prompting before each privileged step.

git clone https://github.com/gnachman/iTerm2.git

Then run the interactive setup. It will prompt before installing Homebrew, before running sudo xcode-select, before accepting the Xcode license, and before installing the SF Symbols cask. If you would rather not answer prompts, the README documents make dangerous-setup as the way to skip all confirmations.

make setup

After setup, native dependencies are compiled in a sandbox and then the app is built. The README notes that make paranoid-deps should be re-run whenever your active Xcode version changes, because the file last-xcode-version tracks which version was last used.

make paranoid-deps
make
make Development
make run

For a universal arm64 + x86_64 binary the README gives UNIVERSAL=1 make Development, and for signing with the project's identity, SIGNED=1 make Development. Code signing is disabled by default. If you prefer Xcode, the README points at tools/set_team_id.sh YOUR_TEAM_ID to set DEVELOPMENT_TEAM.

For a first real use, the tmux integration is the shortest path to seeing what the emulator does differently. Inside a session, start tmux in control mode:

tmux -CC

According to the README, tmux windows then become real macOS windows rather than a text interface inside one pane, and the sessions survive a disconnect from the tmux server.

Where iTerm2 is the wrong tool

The hard boundary is the operating system. The README states macOS as the platform and gives no Linux or Windows installation path. The Makefile sets DEPLOYMENT_TARGET=13.0 and drives xcodebuild, so a source build assumes a Mac with Xcode. Anyone searching for iTerm2 on Linux will not find an answer in this repository.

The second limitation is build cost. The README is explicit that make setup is interactive and prompts before each privileged step, and that make paranoid-deps compiles OpenSSL, libsixel, libgit2 and Sparkle inside a sandbox. That is a real time and disk commitment for a terminal emulator. There is a reason the README offers the nightly build "without building" as an alternative.

The third is the AI Chat feature. The README says the built-in LLM chat window can optionally interact with terminal contents, link sessions for context-aware help, run commands on your behalf, or explain output with annotations. Treat that as a capability with a trust boundary you set yourself. The README does not describe a sandbox, an approval step or a local-model option for that chat, so where your terminal contents go is not answered by the documentation.

Finally, the licence. iTerm2 is GPL-2.0. If you plan to embed it, fork it into a closed product, or ship a modified binary, the GPL-2.0 terms apply to the whole work. That is a licensing question for your own counsel, not something the README resolves.

iTerm2 versus Ghostty and versus Terminal.app

The RELATED searches list includes "iterm2 vs ghostty" and "iterm2 vs terminal", so the comparison is worth making concrete rather than gesturing at "features".

Against Terminal.app, the difference is state. Apple's terminal gives you a window and a shell. iTerm2 adds a session server that outlives the GUI, shell integration that tracks commands, directories, hostnames and usernames, marks at each prompt, and a Python API for extending the emulator. If you open a terminal twice a week, that is overhead. If you keep six SSH sessions open across a laptop sleep cycle, it is the point.

Against Ghostty, the README does not mention Ghostty at all, so any claim about how the two compare would be invented. What can be said from this repository is what iTerm2 itself commits to: tmux control mode, a Python scripting API, inline images, a built-in web browser with browser profiles in the same window hierarchy, triggers, smart selection, copy mode and instant replay. Those are the features to check against whatever else you are evaluating. If a competing emulator implements tmux -CC as native windows and exposes a comparable scripting API, the decision comes down to which one your team already runs.

One more difference worth naming: iTerm2 is Objective-C with a large Xcode project, while newer emulators in this space are often written in Rust. If you intend to contribute patches rather than just use the app, the language and build system matter more than the feature list, and this repository asks you to learn xcodebuild, cmake, cbindgen and a Metal toolchain before your first commit.

Maintenance, upgrade cost and the GPL-2.0 licence

The repository is not archived, and the last push was on 2026-09-21, which is the same day this is being written. That is the only maintenance signal available here: recent commit activity, not a release cadence. No recent releases were retrieved, so there is no version history to reason about. The README's version badge says 3.6, and the Makefile derives VERSION from version.txt, substituting an extra field with a compact date.

Upgrade cost for users of the official build is low: download the app and your sessions survive, because they live in server processes rather than in the GUI. That is the design claim in the README, and it is the reason an app upgrade does not cost you your shells.

Upgrade cost for people building from source is higher and is documented. Re-run make paranoid-deps whenever your active Xcode version changes. If your Xcode version differs from the one committed in last-xcode-version, the README suggests git update-index --skip-worktree last-xcode-version to suppress the noise without committing your local version, with git update-index --no-skip-worktree last-xcode-version to undo it. That is a small piece of git bookkeeping most projects do not require, and it exists because the build is sensitive to the toolchain version.

The licence is GPL-2.0. The repository carries both COPYING and LICENSE files, plus a README.license. Distributing a modified iTerm2, or linking it into a product you ship, brings GPL-2.0 obligations with it. Nothing in the README describes an exception or a commercial licence, so plan accordingly.

Editorial conclusion

Adopt iTerm2 if you work on macOS and want session restoration, tmux control mode, shell integration or a Python API in one emulator. Do not adopt it if you need a terminal on Linux or Windows: the README states the platform is macOS and gives no other build path. Before committing to a source build, verify that your Xcode version matches the committed last-xcode-version file, or run git update-index --skip-worktree last-xcode-version so local version drift does not pollute your checkout.

Frequently asked questions

Official sources

1. gnachman/iTerm2 on GitHub
2. Issues
3. License: GPL-2.0
4. Project website
5. README