---
id: iterm2
version: "2.20"
license: GPLv2
license_treatment: copyleft
maintenance: active
---

# iterm2 — Python interface to iTerm2's scripting API

License: copyleft · Maintenance: active · Downloads: 89.5K/mo

## What it is and what it does

This package is a Python client library that connects to iTerm2's scripting API via WebSocket and Protocol Buffers, allowing you to automate and customize iTerm2 from Python code. It lets you programmatically create and manage terminal sessions, windows, and tabs; read and write terminal content; trigger actions based on patterns; build custom status bar components; and integrate external tools into iTerm2's workflow. The library is primarily used by developers who want to extend iTerm2 with custom automation, build terminal-based tools that interact with iTerm2 sessions, or create sophisticated shell integration workflows.

The package depends on protobuf for message serialization and websockets for real-time communication with the iTerm2 application. It is maintained actively and has low installation friction, making it straightforward to add to a macOS development environment. However, it is strictly macOS-only and requires iTerm2 to be installed and running; it is not a terminal emulator itself but rather a control interface to one.

Use it for:

- Build custom status bar components that display git branch, system metrics, or application state in iTerm2 sessions.
- Automate multi-window terminal workflows by creating and managing sessions, panes, and tabs programmatically.
- Create regex-based triggers that run Python scripts to parse terminal output and take actions like sending notifications or opening files.
- Integrate external tools or services into iTerm2 by scripting session creation, command execution, and result capture.
- Build custom shell integration features that track commands, directories, and metadata across SSH sessions.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a Python scripting interface to iTerm2's automation and customization API, enabling programmatic control of terminal sessions, windows, and features on macOS.

Yes, if you use iTerm2 on macOS and want to automate terminal workflows or build custom terminal features via Python. The package is actively maintained, has low install friction, and exposes a substantial API surface. The GPLv2 license is permissive for personal or internal use but requires source disclosure if you distribute modifications. No known security vulnerabilities. Install it only if you are on macOS and have iTerm2 already in use.

## Install

pip install iterm2
uv add iterm2
poetry add iterm2

## Installing iterm2

Before you install: Low install friction with just two runtime dependencies (protobuf and websockets). Active maintenance with a recent release 71 days ago and ongoing repository activity.

License in practice: GPLv2 copyleft license means any derivative work or modification must also be released under GPLv2. Use is unrestricted for personal or internal projects, but distribution of modified versions requires source code disclosure.

Quickstart:

pip install iterm2

import iterm2

async def main(connection):
    app = await iterm2.async_get_app(connection)
    # Access sessions, windows, and automate iTerm2 features

iterm2.run_until_complete(main)

Requires macOS and iTerm2 application to be installed; Python scripting API is only available on macOS.

Verify before relying:

- Whether the package supports modern Python versions beyond 3.6 (classifier shows 3.6 but requires_python is unspecified)
- Specific scope of automation capabilities and whether all iTerm2 features are exposed via the Python API
- Whether the websockets and protobuf dependencies are pinned to specific versions or have compatibility constraints

## Package facts

- License: GPLv2 (copyleft)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 89.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

iterm2 python scripting api, terminal automation macos, iterm2 session control, python iterm2 integration, macos terminal scripting, iterm2 custom triggers, terminal status bar automation, macos-only, terminal-automation, websocket-client

[View on SkillFed](https://skillfed.io/packages/iterm2) · [View on PyPI](https://pypi.org/project/iterm2/)