Table of Contents

Automatic Profile Switching

WARNING: This document is for an older version of iTerm2.

iTerm2 can use information it knows about your current path, host name, and user name to change profiles. For example, your window's background color or the terminal's character encoding could change when connecting to different hosts.

Shell Integration Required

You must install Shell Integration on all machines and all user accounts where you plan to use Automatic Profile Switching (either by using the scripts or the Triggers workaround described in the Shell Integration docs).

Rule Syntax

In Preferences>Profiles>Advanced, you may specify a set of rules.

When any session satisfies a rule in a given profile, it will switch to that profile. Rules consist of three optional components: the user name, the hostname, and the path. At least one component must be present, since an empty rule is not allowed. The hostname is required only when both a user name and a path are specified.

A user name is a unix accont name (e.g., root) followed by an @.

A path always begins with a /. Any time a hostname is followed by a path, they are separated by a :. For example, iterm2.com:/users/george. It may include * wildcards.

A hostname can be a DNS name, like iterm2.com or an IP address like 127.0.0.1. A hostname may contain one or more * characters, which act as a wildcard (like globbing in Unix).

Some examples:

  • [email protected]:/users/george
  • george@*:/users/george
  • *:/users/george
  • *.iterm2.com:/users/george
  • dev.*.com:/users/george
  • [email protected]
  • iterm2.com
  • george@
  • iterm2.com:/users/george
  • /users/george
  • /users/*

Because more than one rule may match at any given time, more complex rules will take priority over less complex rules. The priority order is defined like this:

  • A username, hostname, and path. For example, "[email protected]:/Users/george".
  • A username and path, using "*" for the hostname. For example, "george@*:/Users/george".
  • A combination of username and hostname. For example, "[email protected]".
  • A hostname and path. For example, "iterm2.com:/Users/george".
  • A hostname. For example, "iterm2.com".
  • A username alone. For example, "george@".
  • A path alone. For example, "/Users/george".

The UI tries to prevent you from entering the same rule in two different profiles, but if that does happen then one profile is chosen arbitrarily.

Automatic Reversion

After APS switches a session's profile, its rules may eventually cease to match (for example, the hostname changes back to "localhost" because an ssh session ends). If no profile has a matching rule, the session's original profile will be restored.

Implementation

Each session maintains a stack of profiles. Initially, the stack contains the profile the session was created with. When the username, hostname, or path changes, iTerm2 finds the best-matching profile. If some profile has a matching rule, one of two things happens:

  • If that profile is already on the stack, profiles above that one will be removed from the stack and the session will switch to that profile.
  • Failing that, the profile will be pushed on the stack and the session will switch to that profile.

If no profile has a matching rule, the stack is emptied (except for the first entry, the original profile for the session) and the session reverts to its original profile.

Rules may begin with ! to indicate "stickiness". A sticky rule causes its profile to stay even after the rule no longer applies, so long as no other rule matches.

Triggers

Since it's impractical to install shell integration everywhere (for example, as root), there will be times when you need to write a trigger to detect the current username or hostname. Please see the Triggers section of Shell Integration for details.

Troubleshooting

There are a few ways things can go wrong. Please see the Why doesn't secure copy/automatic profile switching work? document for help diagnosing and fixing these issues.