# Source: https://iterm2.com/documentation-dynamic-profiles.html

[Table of Contents](#)

Introduction

- [Highlights for New Users](https://iterm2.com/documentation-highlights.html)

- [General Usage](https://iterm2.com/documentation-general-usage.html)

User Interface

- [Menu Items](https://iterm2.com/documentation-menu-items.html)

- [Settings](https://iterm2.com/documentation-preferences.html)

- [Touch Bar](https://iterm2.com/documentation-touch-bar.html)

- [Copy Mode](https://iterm2.com/documentation-copymode.html)

- [Fonts](https://iterm2.com/documentation-fonts.html)

- [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html)

- [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html)

- [Status Bar](https://iterm2.com/documentation-status-bar.html)

Features

- [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html)

- [Badges](https://iterm2.com/documentation-badges.html)

- [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html)

- [Captured Output](https://iterm2.com/documentation-captured-output.html)

- [Coprocesses](https://iterm2.com/documentation-coprocesses.html)

- [Hotkeys](https://iterm2.com/documentation-hotkey.html)

- [Session Restoration](https://iterm2.com/documentation-restoration.html)

- [Shell Integration](https://iterm2.com/documentation-shell-integration.html)

- [Smart Selection](https://iterm2.com/documentation-smart-selection.html)

- [tmux Integration](https://iterm2.com/documentation-tmux-integration.html)

- [Triggers](https://iterm2.com/documentation-triggers.html)

- [Utilities](https://iterm2.com/documentation-utilities.html)

- [Web Browser](https://iterm2.com/documentation-web.html)

- [AI Chat](https://iterm2.com/documentation-ai-chat.html)

Scripting

- [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html)

- [Scripting Variables](https://iterm2.com/documentation-variables.html)

- [Python API](https://iterm2.com/python-api)

- [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html)

Advanced

- [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html)

- [Inline Images Protocol](https://iterm2.com/documentation-images.html)

- [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html)

# Dynamic Profiles

*Dynamic Profiles* is a feature that allows you to store your profiles in a file outside the usual macOS settings database. Profiles may be changed at runtime by editing one or more plist files (formatted as JSON, XML, or in binary). Changes are picked up immediately.

### Availability

Dynamic Profiles are available in iTerm2 2.9.20140923 and later.

### Usage

When iTerm2 starts, it creates a folder:

```

~/Library/Application Support/iTerm2/DynamicProfiles

```

While iTerm2 runs, it monitors the contents of that folder. Any time the folder's contents change, all files in it are reloaded.

Files in this folder are expected to be formatted as Apple [Property Lists](https://en.wikipedia.org/wiki/Property_list). No particular file extension is required. All files in the folder must be valid property lists. If any is malformed, then no changes will be processed.

### Property List Format

A property list describes a data structure consisting of arrays, dictionaries, strings, integers, and boolean values. Property lists may be written in JSON or XML. Here's an example of the skeletal structure of a JSON property list that iTerm2 expects for Dynamic Profiles:

```

{
  "Profiles": [
    {
       [attributes for the first profile go here]
    },
    {
       [attributes for the second profile go here]
    },
    [more profiles]
  ]
}

```

There are two required fields for each profile:

- Guid

- Name

The "Guid" is a globally unique identifier. It is used to track changes to the profile over time. No other profile should ever have the same guid. One easy way to generate a Guid is to use the *uuidgen* program, which comes standard with macOS.

The "Name" is the name, as seen in the Profiles window or in Settings.

Here is a fully formed (but minimal) Dynamic Profiles plist:

```

{
  "Profiles": [
    {
      "Name": "Example",
      "Guid": "ba19744f-6af3-434d-aaa6-0a48e0969958"
    }
  ]
}

```

### Editing

The only way to change a dynamic profile is to modify its parent profile or to modify the property list file. If you change its properties through the Settings UI those changes will *not* be reflected in the property list.

### Attributes

Every profile preference that iTerm2 supports may be an attribute of a Dynamic Profile. Since there are dozens of attributes, you usually won't specify them all. Any attribute not specified will inherit its value from the default profile, or a specified "parent" profile (see below).

The easiest way to find the name and legal value of a profile attribute is to copy it from a known-good reference. To get the JSON for a profile you already have, follow these steps:

- Open Settings > Profiles

- Select a profile

- Open the *Other Actions* menu beneath the list of profiles

- Select *Save Profile as JSON*

- Open the file in your favorite editor.

If you use this as the basis of a Dynamic Profile, remember to chantge the Guid. A Dynamic Profile with a Guid equal to an existing Guid of a regular profile will be ignored.

#### Parent Profiles

Normally, a dynamic profile inherits any attributes you don't explicitly specify from the default profile. You may also specify a particular profile to inherit from using the `Dynamic Profile Parent Name` attribute. The value it takes is a profile name (that is, the name you see listed in the list of profiles in Settings box). Profile names are not guaranteed to be unique, but they are more convenient than GUIDs. If no profile with the specified name is found, the default profile is used instead. For example:

Starting in version 3.4.9, `Dynamic Profile Parent GUID` is another way to specify a parent. It takes precedence over `Dynamic Profile Parent Name`.

```

{
  "Profiles": [
    {
      "Name": "Example",
      "Guid": "ba19744f-6af3-434d-aaa6-0a48e0969958",
      "Dynamic Profile Parent Name": "Light Background"
    }
  ]
}

```

#### Rewritable

You can mark a dynamic profile as "rewritable" which means iTerm2 can make changes to the file on disk to reflect changes made in the settings UI. Simply add `"Rewritable": true` to your profile to enable rewritability.

### Minutiae

Dynamic profiles are loaded in alphabetical order by filename. Within a particular file, they are loaded in the order they're listed in. This only matters if one dynamic profile references another dynamic profile as its parent; the parent should be placed so it loads before any of its children. For all other purposes, the filenames don't matter.

The *Dynamic* will automatically be added to all Dynamic Profiles.

### Troubleshooting

If something goes wrong loading a Dynamic Profile, errors will be logged to Console.app.

### Triggers

By default, *Highlight* triggers save colors in a large inscrutable mess of a format. For dynamic profiles, you can use `{#rrggbb,#rrggbb}` in place of the large inscrutable mess. The first value gives the foreground color and the second value gives the background color. Replace either `#rrggbb` with an empty string to not change that color. For example, to make the foreground red without changing the background use `#{ff0000,}`.

### Example

Here's an example for a common use case: a list of profiles for *ssh*ing to various hosts. In this example, I've used the hostname as the Guid, which makes constructing this file a little easier and works well enough.

```

{
  "Profiles": [
    {
       "Name": "foo.example.com",
       "Guid": "foo.example.com",
       "Custom Command" : "Yes",
       "Command" : "ssh foo.example.com",
    },
    {
       "Name": "bar.example.com",
       "Guid": "bar.example.com",
       "Custom Command" : "Yes",
       "Command" : "ssh bar.example.com",
    },
  ]
}

```