iterm2
Python interface to iTerm2's scripting API
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires macOS and iTerm2 application to be installed; Python scripting API is only available on macOS.
- 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 · maintenance · safety
GPLv2 (copyleft) — 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.
last release 2026-06-04 (71 days) · last repo commit 2026-08-14 · 17,930 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 89,465 downloads/mo, #13,658 on PyPI
Alternatives
Verify before relying
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)- 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
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 on this page. Verify before relying on it.
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
iterm2 on PyPI
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.
Requires macOS and iTerm2 application to be installed; Python scripting API is only available on macOS.
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)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 | Not specified |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 2 packagesprotobufwebsockets |
| Maintenance | Actively maintained 71 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 89,465 / month, #13,658 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 3 - AlphaLicense :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)Programming Language :: Python :: 3.6 |
Evidence: iterm2-2.20-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “iterm2 python scripting api”
- iterm2Provides a Python scripting interface to iTerm2's automation and…
- imgcatDisplays images in iTerm2, WezTerm, and tmux by rendering them…
- pyaedtPyAEDT provides a Python API to script and automate Ansys Electronics…
Give your agent the search over MCP, or paste the wish link into any chat.
More Terminals packages
Wraps any iterable to display a real-time progress bar in the terminal or Jupyter notebook, showing iteration count, elapsed time, and estimated time remaining.
Rich renders styled text, tables, progress bars, syntax highlighting, markdown, and tracebacks to the terminal with minimal code.
Colorama makes ANSI escape sequences for colored terminal text work on Windows by intercepting and converting them to win32 API calls, while passing through unchanged on other platforms.
Install it if you need colored terminal output to work on Windows or want to use ANSI-based libraries portably; skip it only if you target non-Windows platforms…
Measures the displayed width of Unicode strings in terminals, accounting for wide characters, combining marks, and terminal escape sequences that standard Python string functions mishandle.
Install it if your application formats text for terminals and handles non-ASCII characters.
Run a subprocess in a pseudo terminal (pty) and interact with its input and output, enabling automation of interactive programs that require terminal features like password prompts or curses-style interfaces.
However, note that it is aging (last release 2020-12-28) and not actively maintained; it works well for its narrow, well-defined purpose but won't receive updates for…
Pexpect spawns and controls interactive console applications by sending input and matching output patterns, automating tasks that would otherwise require manual interaction.
See also imgcat · libtmux · pairmux · tmuxp · jupyter-server-terminals · paramiko-expect · keyboard · pyobjc-framework-ScreenTime · PyAutoGUI · iterfzf