Documentation | Python API

Profile¶

Provides classes for representing, querying, and modifying iTerm2 profiles.

class Profile(session_id, connection, profile_property_list)¶

Represents a profile.

If a session_id is set then this is the profile attached to a session. Otherwise, it is a shared profile.

property advanced_working_directory_pane_directory: str¶

Returns the advanced working directory pane directory.

Returns: A str

property advanced_working_directory_pane_setting: iterm2.profile.InitialWorkingDirectory¶

Returns the advanced working directory pane setting.

Value excludes Advanced.

Returns: An InitialWorkingDirectory

property advanced_working_directory_tab_directory: str¶

Returns the advanced working directory tab directory.

Returns: A str

property advanced_working_directory_tab_setting: iterm2.profile.InitialWorkingDirectory¶

Returns the advanced working directory tab setting.

Value excludes Advanced.

Returns: An InitialWorkingDirectory

property advanced_working_directory_window_directory: str¶

Returns the advanced working directory window directory.

Returns: A str

property advanced_working_directory_window_setting: iterm2.profile.InitialWorkingDirectory¶

Returns the advanced working directory window setting.

Value excludes Advanced.

Returns: An InitialWorkingDirectory

property all_properties¶: Returns the internal dictionary value.

property allow_title_reporting: bool¶

Returns whether the session title can be reported

Returns: A bool

property allow_title_setting: bool¶

Returns whether the session title can be changed by escape sequence

Returns: A bool

property ambiguous_double_width: bool¶

Returns whether ambiguous-width text should be treated as double-width.

Returns: A bool

property ansi_0_color: iterm2.color.Color¶

Returns the ANSI 0 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_10_color: iterm2.color.Color¶

Returns the ANSI 10 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_11_color: iterm2.color.Color¶

Returns the ANSI 11 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_12_color: iterm2.color.Color¶

Returns the ANSI 12 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_13_color: iterm2.color.Color¶

Returns the ANSI 13 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_14_color: iterm2.color.Color¶

Returns the ANSI 14 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_15_color: iterm2.color.Color¶

Returns the ANSI 15 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_1_color: iterm2.color.Color¶

Returns the ANSI 1 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_2_color: iterm2.color.Color¶

Returns the ANSI 2 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_3_color: iterm2.color.Color¶

Returns the ANSI 3 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_4_color: iterm2.color.Color¶

Returns the ANSI 4 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_5_color: iterm2.color.Color¶

Returns the ANSI 5 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_6_color: iterm2.color.Color¶

Returns the ANSI 6 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_7_color: iterm2.color.Color¶

Returns the ANSI 7 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_8_color: iterm2.color.Color¶

Returns the ANSI 8 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property ansi_9_color: iterm2.color.Color¶

Returns the ANSI 9 color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property answerback_string: str¶

Returns the answerback string.

Returns: A str

property application_keypad_allowed: bool¶

Returns whether the terminal may be placed in application keypad mode

Returns: A bool

property ascii_anti_aliased: bool¶

Returns whether ASCII text is anti-aliased.

Returns: A bool

property ascii_ligatures: bool¶

Returns whether ligatures should be used for ASCII text.

Returns: A bool

async static async_get(connection, guids=None) → List[iterm2.profile.Profile]¶

Fetches all profiles with the specified GUIDs.

Parameters: guids – The profiles to get, or if None then all will be returned.
Returns: A list of Profile objects.

async static async_get_default(connection) → iterm2.profile.Profile ¶: Returns the default profile.

async async_make_default()¶: Makes this profile the default profile.

async async_set_advanced_working_directory_pane_directory(value: str)¶

Sets the advanced working directory pane directory.

Parameters: value (str) – A str

async async_set_advanced_working_directory_pane_setting(value: iterm2.profile.InitialWorkingDirectory)¶

Sets the advanced working directory pane setting.

Value excludes Advanced.

async async_set_advanced_working_directory_tab_directory(value: str)¶

Sets the advanced working directory tab directory.

Parameters: value (str) – A str

async async_set_advanced_working_directory_tab_setting(value: iterm2.profile.InitialWorkingDirectory)¶

Sets the advanced working directory tab setting.

Value excludes Advanced.

async async_set_advanced_working_directory_window_directory(value: str)¶

Sets the advanced working directory window directory.

Parameters: value (str) – A str

async async_set_advanced_working_directory_window_setting(value: iterm2.profile.InitialWorkingDirectory)¶

Sets the advanced working directory window setting.

Value excludes Advanced.

async async_set_allow_title_reporting(value: bool)¶

Sets whether the session title can be reported

Parameters: value (bool) – A bool

async async_set_allow_title_setting(value: bool)¶

Sets whether the session title can be changed by escape sequence

Parameters: value (bool) – A bool

async async_set_ambiguous_double_width(value: bool)¶

Sets whether ambiguous-width text should be treated as double-width.

Parameters: value (bool) – A bool

async async_set_ansi_0_color(value: iterm2.color.Color)¶

Sets the ANSI 0 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_10_color(value: iterm2.color.Color)¶

Sets the ANSI 10 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_11_color(value: iterm2.color.Color)¶

Sets the ANSI 11 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_12_color(value: iterm2.color.Color)¶

Sets the ANSI 12 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_13_color(value: iterm2.color.Color)¶

Sets the ANSI 13 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_14_color(value: iterm2.color.Color)¶

Sets the ANSI 14 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_15_color(value: iterm2.color.Color)¶

Sets the ANSI 15 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_1_color(value: iterm2.color.Color)¶

Sets the ANSI 1 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_2_color(value: iterm2.color.Color)¶

Sets the ANSI 2 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_3_color(value: iterm2.color.Color)¶

Sets the ANSI 3 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_4_color(value: iterm2.color.Color)¶

Sets the ANSI 4 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_5_color(value: iterm2.color.Color)¶

Sets the ANSI 5 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_6_color(value: iterm2.color.Color)¶

Sets the ANSI 6 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_7_color(value: iterm2.color.Color)¶

Sets the ANSI 7 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_8_color(value: iterm2.color.Color)¶

Sets the ANSI 8 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_ansi_9_color(value: iterm2.color.Color)¶

Sets the ANSI 9 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_answerback_string(value: str)¶

Sets the answerback string.

Parameters: value (str) – A str

async async_set_application_keypad_allowed(value: bool)¶

Sets whether the terminal may be placed in application keypad mode

Parameters: value (bool) – A bool

async async_set_ascii_anti_aliased(value: bool)¶

Sets whether ASCII text is anti-aliased.

Parameters: value (bool) – A bool

async async_set_ascii_ligatures(value: bool)¶

Sets whether ligatures should be used for ASCII text.

Parameters: value (bool) – A bool

async async_set_automatic_profile_switching_rules(value: List[str])¶

Sets the automatic profile switching rules.

Value is a list of strings, each giving a rule.

async async_set_background_color(value: iterm2.color.Color)¶

Sets the background color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_background_image_location(value: str)¶

Sets or clears the path to a background image.

The value is a string with the path to the image file, or an empty string to clear the setting.

Parameters: value (str) – A str

async async_set_background_image_mode(value: iterm2.profile.BackgroundImageMode)¶

Sets how the background image is drawn.

Parameters: value (BackgroundImageMode) – A BackgroundImageMode

async async_set_badge_color(value: iterm2.color.Color)¶

Sets the badge color. The alpha value is respected. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_badge_font(value: str)¶

Sets the font of the badge.

The font name is a string like “Helvetica”.

async async_set_badge_max_height(value: int)¶

Sets the max height of the badge.

The value is in points.

async async_set_badge_max_width(value: int)¶

Sets the max width of the badge.

The value is in points.

async async_set_badge_right_margin(value: int)¶

Sets the right margin of the badge.

The value is in points.

async async_set_badge_text(value: str)¶

Sets the badge text.

Parameters: value (str) – A str

async async_set_badge_top_margin(value: int)¶

Sets the top margin of the badge.

The value is in points.

async async_set_blend(value: float)¶

Sets how much the default background color gets blended with the background image.

The value is in 0 to 1.

async async_set_blink_allowed(value: bool)¶

Sets whether blinking text is allowed.

Parameters: value (bool) – A bool

async async_set_blinking_cursor(value: bool)¶

Sets whether the cursor blinks.

Parameters: value (bool) – A bool

async async_set_blur(value: bool)¶

Sets whether background blur should be enabled.

Parameters: value (bool) – A bool

async async_set_blur_radius(value: float)¶

Sets the blur radius (how blurry). Requires blur to be enabled.

The value is between 0 and 30.

async async_set_bm_growl(value: bool)¶

Sets whether notifications should be shown.

Parameters: value (bool) – A bool

async async_set_bold_color(value: iterm2.color.Color)¶

Sets the bold text color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_character_encoding(value: iterm2.profile.CharacterEncoding)¶

Sets the character encoding

Parameters: value (CharacterEncoding) – A CharacterEncoding

async async_set_close_sessions_on_end(value: bool)¶

Sets whether the session should close when it ends.

Parameters: value (bool) – A bool

async async_set_color_preset(preset: iterm2.colorpresets.ColorPreset)¶

Sets the color preset.

Parameters: preset (ColorPreset) – The new value.

See also

Example “Per-Host Colors”
Example “Random Color Preset”
Example “Change Color Presets On Theme Change”
Example “Change Color Preset by Time of Day”

async async_set_command(value: str)¶

Sets the command to run when the session starts.

The value is a string giving the command to run

async async_set_cursor_boost(value: float)¶

Sets the cursor boost level, in 0 to 1. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (float) – A float

async async_set_cursor_color(value: iterm2.color.Color)¶

Sets the cursor color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_cursor_guide_color(value: iterm2.color.Color)¶

Sets the cursor guide color. The alpha value is respected. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_cursor_text_color(value: iterm2.color.Color)¶

Sets the cursor text color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_cursor_type(value: iterm2.profile.CursorType)¶

Sets the cursor type

Parameters: value (CursorType) – A CursorType

async async_set_custom_directory(value: str)¶

Sets the initial working directory.

The initial_directory_mode must be set to InitialWorkingDirectory.INITIAL_WORKING_DIRECTORY_CUSTOM for this to take effect.

async async_set_custom_icon_path(value: str)¶

Sets the path of the custom icon.

The icon_mode must be set to CUSTOM.

async async_set_custom_window_title(value: Optional[str])¶

Sets the custom window title.

This will only be used if use_custom_window_title is True. The value is an interpolated string.

async async_set_disable_printing(value: bool)¶

Sets whether printing by escape sequence is disabled.

Parameters: value (bool) – A bool

async async_set_disable_smcup_rmcup(value: bool)¶

Sets whether alternate screen mode is disabled

Parameters: value (bool) – A bool

async async_set_disable_window_resizing(value: bool)¶

Sets whether the terminal can resize the window with an escape sequence.

Parameters: value (bool) – A bool

async async_set_flashing_bell(value: bool)¶

Sets whether the bell should flash the screen

Parameters: value (bool) – A bool

async async_set_foreground_color(value: iterm2.color.Color)¶

Sets the foreground color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_horizontal_spacing(value: float)¶

Sets the fraction of horizontal spacing. Must be non-negative.

Parameters: value (float) – A float

async async_set_icon_mode(value: iterm2.profile.IconMode)¶

Sets the icon mode.

Parameters: value (IconMode) – An IconMode

async async_set_idle_code(value: int)¶

Sets the ASCII code to send on idle

Value is an int in 0 through 255.

async async_set_idle_period(value: float)¶

Sets how often to send a code when idle

Value is a float at least 0

async async_set_initial_directory_mode(value: iterm2.profile.InitialWorkingDirectory)¶

Sets whether to use a custom (not home) initial working directory.

Parameters: value (InitialWorkingDirectory) – An InitialWorkingDirectory

async async_set_key_mappings(value: Dict[str, Any])¶

Sets the keyboard shortcuts.

The value is a Dictionary mapping keystroke to action. You can convert between the values in this dictionary and a KeyBinding using iterm2.decode_key_binding

async async_set_left_option_key_changeable(value: bool)¶

Sets whether apps should be able to change the left option key to send esc+.

The values gives whether it should be allowed.

async async_set_left_option_key_sends(value: iterm2.profile.OptionKeySends)¶

Sets the behavior of the left option key.

Parameters: value (OptionKeySends) – An OptionKeySends

async async_set_link_color(value: iterm2.color.Color)¶

Sets the link color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_minimum_contrast(value: float)¶

Sets the minimum contrast, in 0 to 1. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (float) – A float

async async_set_mouse_reporting(value: bool)¶

Sets whether mouse reporting is allowed

Parameters: value (bool) – A bool

async async_set_mouse_reporting_allow_mouse_wheel(value: bool)¶

Sets whether mouse reporting reports the mouse wheel’s movements.

Parameters: value (bool) – A bool

async async_set_name(value: str)¶

Sets the name.

Parameters: value (str) – A str

async async_set_non_ascii_anti_aliased(value: bool)¶

Sets whether non-ASCII text is anti-aliased.

Parameters: value (bool) – A bool

async async_set_non_ascii_font(value: str)¶

Sets the non-ASCII font.

This is used for non-ASCII characters if use_non_ascii_font is enabled. The value is the font name and size as a string.

async async_set_non_ascii_ligatures(value: bool)¶

Sets whether ligatures should be used for non-ASCII text.

Parameters: value (bool) – A bool

async async_set_normal_font(value: str)¶

Sets the normal font.

The normal font is used for either ASCII or all characters depending on whether a separate font is used for non-ascii. The value is a font’s name and size as a string.

See also

Example “Increase Font Size By 6”

async async_set_only_the_default_bg_color_uses_transparency(value: bool)¶

Sets whether window transparency shows through non-default background colors.

Parameters: value (bool) – A bool

async async_set_place_prompt_at_first_column(value: bool)¶

Sets whether the prompt should always begin at the first column (requires shell integration)

Parameters: value (bool) – A bool

async async_set_prompt_before_closing(value: bool)¶

Sets whether the session should prompt before closing.

Parameters: value (bool) – A bool

async async_set_reduce_flicker(value: bool)¶

Sets whether the flicker fixer is on.

Parameters: value (bool) – A bool

async async_set_right_option_key_changeable(value: bool)¶

Sets whether apps should be able to change the right option key to send esc+.

The values gives whether it should be allowed.

async async_set_right_option_key_sends(value: iterm2.profile.OptionKeySends)¶

Sets the behavior of the right option key.

Parameters: value (OptionKeySends) – An OptionKeySends

async async_set_scrollback_in_alternate_screen(value: bool)¶

Sets whether text gets appended to scrollback in alternate screen mode.

Parameters: value (bool) – A bool

async async_set_scrollback_lines(value: int)¶

Sets the number of scrollback lines.

Value must be at least 0.

async async_set_scrollback_with_status_bar(value: bool)¶

Sets whether text gets appended to scrollback when there is an app status bar

Parameters: value (bool) – A bool

async async_set_selected_text_color(value: iterm2.color.Color)¶

Sets the selection text color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_selection_color(value: iterm2.color.Color)¶

Sets the selection background color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_semantic_history(value: Dict[str, Any])¶

Sets the semantic history prefs.

Parameters: value – A typing.Dict[str, typing.Any]

async async_set_send_bell_alert(value: bool)¶

Sets whether notifications should be shown for the bell ringing

Parameters: value (bool) – A bool

async async_set_send_code_when_idle(value: bool)¶

Sets whether to send a code when idle

Parameters: value (bool) – A bool

async async_set_send_idle_alert(value: bool)¶

Sets whether notifications should be shown for becoming idle

Parameters: value (bool) – A bool

async async_set_send_new_output_alert(value: bool)¶

Sets whether notifications should be shown for new output

Parameters: value (bool) – A bool

async async_set_send_session_ended_alert(value: bool)¶

Sets whether notifications should be shown for a session ending

Parameters: value (bool) – A bool

async async_set_send_terminal_generated_alerts(value: bool)¶

Sets whether notifications should be shown for escape-sequence originated notifications

Parameters: value (bool) – A bool

async async_set_session_close_undo_timeout(value: float)¶

Sets the amount of time you can undo closing a session

The value is at least 0.

async async_set_show_mark_indicators(value: bool)¶

Sets whether mark indicators should be visible

Parameters: value (bool) – A bool

async async_set_silence_bell(value: bool)¶

Sets whether the bell makes noise.

Parameters: value (bool) – A bool

async async_set_smart_cursor_color(value: bool)¶

Sets whether to use smart cursor color. This only applies to box cursors. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (bool) – A bool

async async_set_smart_selection_rules(value: List[Dict[str, Any]])¶

Sets the smart selection rules.

The value is a list of dicts of smart selection rules (currently undocumented)

async async_set_status_bar_enabled(value: bool)¶

Sets whether the status bar be enabled.

If True, the status bar will be shown.

async async_set_sync_title(value: bool)¶

Sets whether the profile name stays in the tab title, even if changed by an escape sequence.

Parameters: value (bool) – A bool

async async_set_tab_color(value: iterm2.color.Color)¶

Sets the tab color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

async async_set_thin_strokes(value: iterm2.profile.ThinStrokes)¶

Sets whether thin strokes are used.

Parameters: value (ThinStrokes) – A ThinStrokes

async async_set_title_components(value: List[iterm2.profile.TitleComponents])¶

Sets which components are visible in the session’s title, or selects a custom component.

If it is set to CUSTOM then the title_function must be set properly.

async async_set_title_function(display_name: str, identifier: str)¶

Sets the function call for the session title provider and its display name for the UI.

Parameters: display_name (str) – This is shown in the Title Components menu in the UI.
Identifier: The unique identifier, typically a backwards domain name.

This takes effect only when the title_components property is set to CUSTOM.

async async_set_touchbar_mappings(value: Dict[str, Any])¶

Sets the touchbar actions.

The value is a Dictionary mapping touch bar item to action

async async_set_transparency(value: float)¶

Sets the level of transparency.

The value is between 0 and 1.

async async_set_triggers(value: List[Dict[str, Any]])¶

Sets the triggers.

Value is an encoded trigger. Use iterm2.decode_trigger to convert from an encoded trigger to an object. Trigger objects can be encoded using the encode property.

async async_set_triggers_use_interpolated_strings(value: bool)¶

Sets whether trigger parameters should be interpreted as interpolated strings.

Parameters: value (bool) – A bool

async async_set_underline_color(value: Optional[iterm2.color.Color])¶

Sets the underline color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A typing.Optional[‘iterm2.color.Color’]

async async_set_unicode_normalization(value: iterm2.profile.UnicodeNormalization)¶

Sets the unicode normalization form to use

Parameters: value (UnicodeNormalization) – An UnicodeNormalization

async async_set_unicode_version(value: bool)¶

Sets the unicode version for wcwidth

Parameters: value (bool) – A bool

async async_set_unlimited_scrollback(value: bool)¶

Sets whether the scrollback buffer’s length is unlimited.

Parameters: value (bool) – A bool

async async_set_use_bold_font(value: bool)¶

Sets whether to use the bold variant of the font for bold text.

Parameters: value (bool) – A bool

async async_set_use_bright_bold(value: bool)¶

Sets how bold text is rendered. This is used only when separate light/dark mode colors are not enabled.

This function is deprecated because its behavior changed in iTerm2 version 3.3.7.

Pre-3.3.7, when enabled: * Use the profile-specified bold color for default-colored

bold text.

Dark ANSI colors get replaced with their light counterparts for bold text.

In 3.3.7 and later: * Use the profile-specified bold color for default-colored

bold text.

Use use_bold_color and brighten_bold_text in 3.3.7 and later instead of this method.

async async_set_use_built_in_powerline_glyphs(value: bool)¶

Sets whether powerline glyphs should be drawn by iTerm2 or left to the font.

Parameters: value (bool) – A bool

async async_set_use_csi_u(value: bool)¶

Sets whether to report keystrokes with CSI u protocol.

If True, CSI u will be enabled.

async async_set_use_cursor_guide(value: bool)¶

Sets whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (bool) – A bool

async async_set_use_custom_command(value: str)¶

Sets whether to use a custom command when the session is created.

The value is the string Yes or No

async async_set_use_custom_window_title(value: bool)¶

Sets whether the custom window title is used.

Should the custom window title in the profile be used?

async async_set_use_italic_font(value: bool)¶

Sets whether italic text is allowed.

Parameters: value (bool) – A bool

async async_set_use_non_ascii_font(value: bool)¶

Sets whether to use a different font for non-ASCII text.

Parameters: value (bool) – A bool

async async_set_use_tab_color(value: bool)¶

Sets whether the tab color should be used. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (bool) – A bool

async async_set_use_transparency_initially(value: bool)¶

Sets whether a window created with this profile respect the transparency setting.

If True, use transparency; if False, force the window to be opaque (but it can be toggled with View > Use Transparency).

async async_set_use_underline_color(value: bool)¶

Sets whether to use the specified underline color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (bool) – A bool

async async_set_vertical_spacing(value: float)¶

Sets the fraction of vertical spacing. Must be non-negative.

Parameters: value (float) – A float

async async_set_visual_bell(value: bool)¶

Sets whether a bell should be shown when the bell rings

Parameters: value (bool) – A bool

property automatic_profile_switching_rules: List[str]¶

Returns the automatic profile switching rules.

Value is a list of strings, each giving a rule.

Returns: A typing.List[str]

property background_color: iterm2.color.Color¶

Returns the background color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property background_image_location: str¶

Returns the path to the background image.

Returns: A str

property background_image_mode: iterm2.profile.BackgroundImageMode¶

Returns how the background image is drawn.

Returns: A BackgroundImageMode

property badge_color: iterm2.color.Color¶

Returns the badge color. The alpha value is respected. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property badge_font: str¶

Returns the font of the badge.

The font name is a string like “Helvetica”.

Returns: A str

property badge_max_height: int¶

Returns the max height of the badge.

The value is in points.

Returns: An int

property badge_max_width: int¶

Returns the max width of the badge.

The value is in points.

Returns: An int

property badge_right_margin: int¶

Returns the right margin of the badge.

The value is in points.

Returns: An int

property badge_text: str¶

Returns the badge text.

Returns: A str

property badge_top_margin: int¶

Returns the top margin of the badge.

The value is in points.

Returns: An int

property blend: float¶

Returns how much the default background color gets blended with the background image.

The value is in 0 to 1.

Returns: A float

property blink_allowed: bool¶

Returns whether blinking text is allowed.

Returns: A bool

property blinking_cursor: bool¶

Returns whether the cursor blinks.

Returns: A bool

property blur: bool¶

Returns whether background blur should be enabled.

Returns: A bool

property blur_radius: float¶

Returns the blur radius (how blurry). Requires blur to be enabled.

The value is between 0 and 30.

Returns: A float

property bm_growl: bool¶

Returns whether notifications should be shown.

Returns: A bool

property bold_color: iterm2.color.Color¶

Returns the bold text color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property character_encoding: iterm2.profile.CharacterEncoding¶

Returns the character encoding

Returns: A CharacterEncoding

property close_sessions_on_end: bool¶

Returns whether the session should close when it ends.

Returns: A bool

property command: str¶

Returns the command to run when the session starts.

The value is a string giving the command to run

Returns: A str

property cursor_boost: float¶

Returns the cursor boost level, in 0 to 1. This is used only when separate light/dark mode colors are not enabled.

Returns: A float

property cursor_color: iterm2.color.Color¶

Returns the cursor color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property cursor_guide_color: iterm2.color.Color¶

Returns the cursor guide color. The alpha value is respected. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property cursor_text_color: iterm2.color.Color¶

Returns the cursor text color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property cursor_type: iterm2.profile.CursorType¶

Returns the cursor type

Returns: A CursorType

property custom_directory: str¶

Returns the initial working directory.

The initial_directory_mode must be set to InitialWorkingDirectory.INITIAL_WORKING_DIRECTORY_CUSTOM for this to take effect.

Returns: A str

property custom_icon_path: str¶

Returns the path of the custom icon.

The icon_mode must be set to CUSTOM.

Returns: A str

property custom_window_title: Optional[str]¶

Returns the custom window title.

This will only be used if use_custom_window_title is True. The value is an interpolated string.

Returns: A typing.Optional[str]

property disable_printing: bool¶

Returns whether printing by escape sequence is disabled.

Returns: A bool

property disable_smcup_rmcup: bool¶

Returns whether alternate screen mode is disabled

Returns: A bool

property disable_window_resizing: bool¶

Returns whether the terminal can resize the window with an escape sequence.

Returns: A bool

property dynamic_profile_file_name¶

If the profile is a dynamic profile, returns the path to the file from which it came.

Returns: String file name

property dynamic_profile_parent_name¶

If the profile is a dynamic profile, returns the name of the parent profile.

Returns: String name

property flashing_bell: bool¶

Returns whether the bell should flash the screen

Returns: A bool

property foreground_color: iterm2.color.Color¶

Returns the foreground color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property guid¶

Returns globally unique ID for this profile.

Returns: A string identifying this profile

property horizontal_spacing: float¶

Returns the fraction of horizontal spacing. Must be non-negative.

Returns: A float

property icon_mode: iterm2.profile.IconMode¶

Returns the icon mode.

Returns: An IconMode

property idle_code: int¶

Returns the ASCII code to send on idle

Value is an int in 0 through 255.

Returns: An int

property idle_period: float¶

Returns how often to send a code when idle

Value is a float at least 0

Returns: A float

property initial_directory_mode: iterm2.profile.InitialWorkingDirectory¶

Returns whether to use a custom (not home) initial working directory.

Returns: An InitialWorkingDirectory

property key_mappings: Dict[str, Any]¶

Returns the keyboard shortcuts.

The value is a Dictionary mapping keystroke to action. You can convert between the values in this dictionary and a KeyBinding using iterm2.decode_key_binding

Returns: A typing.Dict[str, typing.Any]

property left_option_key_changeable: Optional[bool]¶

Returns whether apps should be able to change the left option key to send esc+.

The values gives whether it should be allowed.

Returns: A typing.Optional[bool]

property left_option_key_sends: iterm2.profile.OptionKeySends¶

Returns the behavior of the left option key.

Returns: An OptionKeySends

property link_color: iterm2.color.Color¶

Returns the link color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property local_write_only_copy: iterm2.profile.LocalWriteOnlyProfile¶: Returns a LocalWriteOnlyProfile containing the properties in this profile.

property minimum_contrast: float¶

Returns the minimum contrast, in 0 to 1. This is used only when separate light/dark mode colors are not enabled.

Returns: A float

property mouse_reporting: bool¶

Returns whether mouse reporting is allowed

Returns: A bool

property mouse_reporting_allow_mouse_wheel: bool¶

Returns whether mouse reporting reports the mouse wheel’s movements.

Returns: A bool

property name: str¶

Returns the name.

Returns: A str

property non_ascii_anti_aliased: bool¶

Returns whether non-ASCII text is anti-aliased.

Returns: A bool

property non_ascii_font: str¶

Returns the non-ASCII font.

This is used for non-ASCII characters if use_non_ascii_font is enabled. The value is the font name and size as a string.

Returns: A str

property non_ascii_ligatures: bool¶

Returns whether ligatures should be used for non-ASCII text.

Returns: A bool

property normal_font: str¶

Returns the normal font.

The normal font is used for either ASCII or all characters depending on whether a separate font is used for non-ascii. The value is a font’s name and size as a string.

See also

Example “Increase Font Size By 6”

Returns: A str

property only_the_default_bg_color_uses_transparency: bool¶

Returns whether window transparency shows through non-default background colors.

Returns: A bool

property original_guid¶

The GUID of the original profile from which this one was derived.

Used for sessions whose profile has been modified from the underlying profile. Otherwise not set.

Returns: Guid

property place_prompt_at_first_column: bool¶

Returns whether the prompt should always begin at the first column (requires shell integration)

Returns: A bool

property prompt_before_closing: bool¶

Returns whether the session should prompt before closing.

Returns: A bool

property reduce_flicker: bool¶

Returns whether the flicker fixer is on.

Returns: A bool

property right_option_key_changeable: Optional[bool]¶

Returns whether apps should be able to change the right option key to send esc+.

The values gives whether it should be allowed.

Returns: A typing.Optional[bool]

property right_option_key_sends: iterm2.profile.OptionKeySends¶

Returns the behavior of the right option key.

Returns: An OptionKeySends

property scrollback_in_alternate_screen: bool¶

Returns whether text gets appended to scrollback in alternate screen mode.

Returns: A bool

property scrollback_lines: int¶

Returns the number of scrollback lines.

Value must be at least 0.

Returns: An int

property scrollback_with_status_bar: bool¶

Returns whether text gets appended to scrollback when there is an app status bar

Returns: A bool

property selected_text_color: iterm2.color.Color¶

Returns the selection text color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property selection_color: iterm2.color.Color¶

Returns the selection background color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property semantic_history: Dict[str, Any]¶

Returns the semantic history prefs.

Returns: A typing.Dict[str, typing.Any]

property send_bell_alert: bool¶

Returns whether notifications should be shown for the bell ringing

Returns: A bool

property send_code_when_idle: bool¶

Returns whether to send a code when idle

Returns: A bool

property send_idle_alert: bool¶

Returns whether notifications should be shown for becoming idle

Returns: A bool

property send_new_output_alert: bool¶

Returns whether notifications should be shown for new output

Returns: A bool

property send_session_ended_alert: bool¶

Returns whether notifications should be shown for a session ending

Returns: A bool

property send_terminal_generated_alerts: bool¶

Returns whether notifications should be shown for escape-sequence originated notifications

Returns: A bool

property session_close_undo_timeout: float¶

Returns the amount of time you can undo closing a session

The value is at least 0.

Returns: A float

property show_mark_indicators: bool¶

Returns whether mark indicators should be visible

Returns: A bool

property silence_bell: bool¶

Returns whether the bell makes noise.

Returns: A bool

property smart_cursor_color: bool¶

Returns whether to use smart cursor color. This only applies to box cursors. This is used only when separate light/dark mode colors are not enabled.

Returns: A bool

property smart_selection_rules: List[Dict[str, Any]]¶

Returns the smart selection rules.

The value is a list of dicts of smart selection rules (currently undocumented)

Returns: A typing.List[typing.Dict[str, typing.Any]]

property status_bar_enabled: Optional[bool]¶

Returns whether the status bar be enabled.

If True, the status bar will be shown.

Returns: A typing.Optional[bool]

property sync_title: bool¶

Returns whether the profile name stays in the tab title, even if changed by an escape sequence.

Returns: A bool

property tab_color: iterm2.color.Color¶

Returns the tab color. This is used only when separate light/dark mode colors are not enabled.

Returns: A Color

property thin_strokes: iterm2.profile.ThinStrokes¶

Returns whether thin strokes are used.

Returns: A ThinStrokes

property title_components: Optional[List[iterm2.profile.TitleComponents]]¶

Returns which components are visible in the session’s title, or selects a custom component.

If it is set to CUSTOM then the title_function must be set properly.

property title_function: Optional[Tuple[str, str]]¶

Returns the function call for the session title provider and its display name for the UI.

Returns: (display name, unique identifier)

property touchbar_mappings: Dict[str, Any]¶

Returns the touchbar actions.

The value is a Dictionary mapping touch bar item to action

Returns: A typing.Dict[str, typing.Any]

property transparency: float¶

Returns the level of transparency.

The value is between 0 and 1.

Returns: A float

property triggers: List[Dict[str, Any]]¶

Returns the triggers.

Value is an encoded trigger. Use iterm2.decode_trigger to convert from an encoded trigger to an object. Trigger objects can be encoded using the encode property.

Returns: A typing.List[typing.Dict[str, typing.Any]]

property triggers_use_interpolated_strings: Optional[bool]¶

Returns whether trigger parameters should be interpreted as interpolated strings.

Returns: A typing.Optional[bool]

property underline_color: Optional[iterm2.color.Color]¶

Returns the underline color. This is used only when separate light/dark mode colors are not enabled.

Returns: A typing.Optional[‘iterm2.color.Color’]

property unicode_normalization: iterm2.profile.UnicodeNormalization¶

Returns the unicode normalization form to use

Returns: An UnicodeNormalization

property unicode_version: bool¶

Returns the unicode version for wcwidth

Returns: A bool

property unlimited_scrollback: bool¶

Returns whether the scrollback buffer’s length is unlimited.

Returns: A bool

property use_bold_font: bool¶

Returns whether to use the bold variant of the font for bold text.

Returns: A bool

property use_bright_bold: bool¶

Returns how bold text is rendered. This is used only when separate light/dark mode colors are not enabled.

This function is deprecated because its behavior changed in iTerm2 version 3.3.7.

Pre-3.3.7, when enabled: * Use the profile-specified bold color for default-colored

bold text.

Dark ANSI colors get replaced with their light counterparts for bold text.

In 3.3.7 and later: * Use the profile-specified bold color for default-colored

bold text.

Use use_bold_color and brighten_bold_text in 3.3.7 and later instead of this method.

Returns: A bool

property use_built_in_powerline_glyphs: bool¶

Returns whether powerline glyphs should be drawn by iTerm2 or left to the font.

Returns: A bool

property use_csi_u: Optional[bool]¶

Returns whether to report keystrokes with CSI u protocol.

If True, CSI u will be enabled.

Returns: A typing.Optional[bool]

property use_cursor_guide: bool¶

Returns whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

Returns: A bool

property use_custom_command: str¶

Returns whether to use a custom command when the session is created.

The value is the string Yes or No

Returns: A str

property use_custom_window_title: bool¶

Returns whether the custom window title is used.

Should the custom window title in the profile be used?

Returns: A bool

property use_italic_font: bool¶

Returns whether italic text is allowed.

Returns: A bool

property use_non_ascii_font: bool¶

Returns whether to use a different font for non-ASCII text.

Returns: A bool

property use_tab_color: bool¶

Returns whether the tab color should be used. This is used only when separate light/dark mode colors are not enabled.

Returns: A bool

property use_transparency_initially: Optional[bool]¶

Returns whether a window created with this profile respect the transparency setting.

If True, use transparency; if False, force the window to be opaque (but it can be toggled with View > Use Transparency).

Returns: A typing.Optional[bool]

property use_underline_color: bool¶

Returns whether to use the specified underline color. This is used only when separate light/dark mode colors are not enabled.

Returns: A bool

property vertical_spacing: float¶

Returns the fraction of vertical spacing. Must be non-negative.

Returns: A float

property visual_bell: bool¶

Returns whether a bell should be shown when the bell rings

Returns: A bool

class LocalWriteOnlyProfile(values=None)¶

A profile that can be modified but not read and does not send changes on each write.

You can safely create this with LocalWriteOnlyProfile(). Use async_set_profile_properties() to update a session without modifying the underlying profile.

See also

Example “Preserve Tab Color”
Example “Set Tab Color”
Example “Increase Font Size By 6”

set_advanced_working_directory_pane_directory(value: str)¶

Sets the advanced working directory pane directory.

Parameters: value (str) – A str

set_advanced_working_directory_pane_setting(value: iterm2.profile.InitialWorkingDirectory)¶

Sets the advanced working directory pane setting.

Value excludes Advanced.

Parameters: value (InitialWorkingDirectory) – An InitialWorkingDirectory

set_advanced_working_directory_tab_directory(value: str)¶

Sets the advanced working directory tab directory.

Parameters: value (str) – A str

set_advanced_working_directory_tab_setting(value: iterm2.profile.InitialWorkingDirectory)¶

Sets the advanced working directory tab setting.

Value excludes Advanced.

Parameters: value (InitialWorkingDirectory) – An InitialWorkingDirectory

set_advanced_working_directory_window_directory(value: str)¶

Sets the advanced working directory window directory.

Parameters: value (str) – A str

set_advanced_working_directory_window_setting(value: iterm2.profile.InitialWorkingDirectory)¶

Sets the advanced working directory window setting.

Value excludes Advanced.

Parameters: value (InitialWorkingDirectory) – An InitialWorkingDirectory

set_allow_title_reporting(value: bool)¶

Sets whether the session title can be reported

Parameters: value (bool) – A bool

set_allow_title_setting(value: bool)¶

Sets whether the session title can be changed by escape sequence

Parameters: value (bool) – A bool

set_ambiguous_double_width(value: bool)¶

Sets whether ambiguous-width text should be treated as double-width.

Parameters: value (bool) – A bool

set_ansi_0_color(value: iterm2.color.Color)¶

Sets the ANSI 0 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_10_color(value: iterm2.color.Color)¶

Sets the ANSI 10 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_11_color(value: iterm2.color.Color)¶

Sets the ANSI 11 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_12_color(value: iterm2.color.Color)¶

Sets the ANSI 12 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_13_color(value: iterm2.color.Color)¶

Sets the ANSI 13 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_14_color(value: iterm2.color.Color)¶

Sets the ANSI 14 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_15_color(value: iterm2.color.Color)¶

Sets the ANSI 15 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_1_color(value: iterm2.color.Color)¶

Sets the ANSI 1 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_2_color(value: iterm2.color.Color)¶

Sets the ANSI 2 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_3_color(value: iterm2.color.Color)¶

Sets the ANSI 3 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_4_color(value: iterm2.color.Color)¶

Sets the ANSI 4 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_5_color(value: iterm2.color.Color)¶

Sets the ANSI 5 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_6_color(value: iterm2.color.Color)¶

Sets the ANSI 6 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_7_color(value: iterm2.color.Color)¶

Sets the ANSI 7 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_8_color(value: iterm2.color.Color)¶

Sets the ANSI 8 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_ansi_9_color(value: iterm2.color.Color)¶

Sets the ANSI 9 color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_answerback_string(value: str)¶

Sets the answerback string.

Parameters: value (str) – A str

set_application_keypad_allowed(value: bool)¶

Sets whether the terminal may be placed in application keypad mode

Parameters: value (bool) – A bool

set_ascii_anti_aliased(value: bool)¶

Sets whether ASCII text is anti-aliased.

Parameters: value (bool) – A bool

set_ascii_ligatures(value: bool)¶

Sets whether ligatures should be used for ASCII text.

Parameters: value (bool) – A bool

set_automatic_profile_switching_rules(value: List[str])¶

Sets the automatic profile switching rules.

Value is a list of strings, each giving a rule.

Parameters: value – A typing.List[str]

set_background_color(value: iterm2.color.Color)¶

Sets the background color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_background_image_location(value: str)¶

Sets or clears the path to a background image.

The value is a string with the path to the image file, or an empty string to clear the setting.

Parameters: value (str) – A str

set_background_image_mode(value: iterm2.profile.BackgroundImageMode)¶

Sets how the background image is drawn.

Parameters: value (BackgroundImageMode) – A BackgroundImageMode

set_badge_color(value: iterm2.color.Color)¶

Sets the badge color. The alpha value is respected. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_badge_font(value: str)¶

Sets the font of the badge.

The font name is a string like “Helvetica”.

Parameters: value (str) – A str

set_badge_max_height(value: int)¶

Sets the max height of the badge.

The value is in points.

Parameters: value (int) – An int

set_badge_max_width(value: int)¶

Sets the max width of the badge.

The value is in points.

Parameters: value (int) – An int

set_badge_right_margin(value: int)¶

Sets the right margin of the badge.

The value is in points.

Parameters: value (int) – An int

set_badge_text(value: str)¶

Sets the badge text.

Parameters: value (str) – A str

set_badge_top_margin(value: int)¶

Sets the top margin of the badge.

The value is in points.

Parameters: value (int) – An int

set_blend(value: float)¶

Sets how much the default background color gets blended with the background image.

The value is in 0 to 1.

Parameters: value (float) – A float

set_blink_allowed(value: bool)¶

Sets whether blinking text is allowed.

Parameters: value (bool) – A bool

set_blinking_cursor(value: bool)¶

Sets whether the cursor blinks.

Parameters: value (bool) – A bool

set_blur(value: bool)¶

Sets whether background blur should be enabled.

Parameters: value (bool) – A bool

set_blur_radius(value: float)¶

Sets the blur radius (how blurry). Requires blur to be enabled.

The value is between 0 and 30.

Parameters: value (float) – A float

set_bm_growl(value: bool)¶

Sets whether notifications should be shown.

Parameters: value (bool) – A bool

set_bold_color(value: iterm2.color.Color)¶

Sets the bold text color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_character_encoding(value: iterm2.profile.CharacterEncoding)¶

Sets the character encoding

Parameters: value (CharacterEncoding) – A CharacterEncoding

set_close_sessions_on_end(value: bool)¶

Sets whether the session should close when it ends.

Parameters: value (bool) – A bool

set_command(value: str)¶

Sets the command to run when the session starts.

The value is a string giving the command to run

Parameters: value (str) – A str

set_cursor_boost(value: float)¶

Sets the cursor boost level, in 0 to 1. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (float) – A float

set_cursor_color(value: iterm2.color.Color)¶

Sets the cursor color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_cursor_guide_color(value: iterm2.color.Color)¶

Sets the cursor guide color. The alpha value is respected. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_cursor_text_color(value: iterm2.color.Color)¶

Sets the cursor text color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_cursor_type(value: iterm2.profile.CursorType)¶

Sets the cursor type

Parameters: value (CursorType) – A CursorType

set_custom_directory(value: str)¶

Sets the initial working directory.

The initial_directory_mode must be set to InitialWorkingDirectory.INITIAL_WORKING_DIRECTORY_CUSTOM for this to take effect.

Parameters: value (str) – A str

set_custom_icon_path(value: str)¶

Sets the path of the custom icon.

The icon_mode must be set to CUSTOM.

Parameters: value (str) – A str

set_custom_window_title(value: Optional[str])¶

Sets the custom window title.

This will only be used if use_custom_window_title is True. The value is an interpolated string.

Parameters: value – A typing.Optional[str]

set_disable_printing(value: bool)¶

Sets whether printing by escape sequence is disabled.

Parameters: value (bool) – A bool

set_disable_smcup_rmcup(value: bool)¶

Sets whether alternate screen mode is disabled

Parameters: value (bool) – A bool

set_disable_window_resizing(value: bool)¶

Sets whether the terminal can resize the window with an escape sequence.

Parameters: value (bool) – A bool

set_flashing_bell(value: bool)¶

Sets whether the bell should flash the screen

Parameters: value (bool) – A bool

set_foreground_color(value: iterm2.color.Color)¶

Sets the foreground color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_horizontal_spacing(value: float)¶

Sets the fraction of horizontal spacing. Must be non-negative.

Parameters: value (float) – A float

set_icon_mode(value: iterm2.profile.IconMode)¶

Sets the icon mode.

Parameters: value (IconMode) – An IconMode

set_idle_code(value: int)¶

Sets the ASCII code to send on idle

Value is an int in 0 through 255.

Parameters: value (int) – An int

set_idle_period(value: float)¶

Sets how often to send a code when idle

Value is a float at least 0

Parameters: value (float) – A float

set_initial_directory_mode(value: iterm2.profile.InitialWorkingDirectory)¶

Sets whether to use a custom (not home) initial working directory.

Parameters: value (InitialWorkingDirectory) – An InitialWorkingDirectory

set_key_mappings(value: Dict[str, Any])¶

Sets the keyboard shortcuts.

The value is a Dictionary mapping keystroke to action. You can convert between the values in this dictionary and a KeyBinding using iterm2.decode_key_binding

Parameters: value – A typing.Dict[str, typing.Any]

set_left_option_key_changeable(value: bool)¶

Sets whether apps should be able to change the left option key to send esc+.

The values gives whether it should be allowed.

Parameters: value (bool) – A bool

set_left_option_key_sends(value: iterm2.profile.OptionKeySends)¶

Sets the behavior of the left option key.

Parameters: value (OptionKeySends) – An OptionKeySends

set_link_color(value: iterm2.color.Color)¶

Sets the link color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_minimum_contrast(value: float)¶

Sets the minimum contrast, in 0 to 1. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (float) – A float

set_mouse_reporting(value: bool)¶

Sets whether mouse reporting is allowed

Parameters: value (bool) – A bool

set_mouse_reporting_allow_mouse_wheel(value: bool)¶

Sets whether mouse reporting reports the mouse wheel’s movements.

Parameters: value (bool) – A bool

set_name(value: str)¶

Sets the name.

Parameters: value (str) – A str

set_non_ascii_anti_aliased(value: bool)¶

Sets whether non-ASCII text is anti-aliased.

Parameters: value (bool) – A bool

set_non_ascii_font(value: str)¶

Sets the non-ASCII font.

This is used for non-ASCII characters if use_non_ascii_font is enabled. The value is the font name and size as a string.

Parameters: value (str) – A str

set_non_ascii_ligatures(value: bool)¶

Sets whether ligatures should be used for non-ASCII text.

Parameters: value (bool) – A bool

set_normal_font(value: str)¶

Sets the normal font.

The normal font is used for either ASCII or all characters depending on whether a separate font is used for non-ascii. The value is a font’s name and size as a string.

See also

Example “Increase Font Size By 6”

Parameters: value (str) – A str

set_only_the_default_bg_color_uses_transparency(value: bool)¶

Sets whether window transparency shows through non-default background colors.

Parameters: value (bool) – A bool

set_place_prompt_at_first_column(value: bool)¶

Sets whether the prompt should always begin at the first column (requires shell integration)

Parameters: value (bool) – A bool

set_prompt_before_closing(value: bool)¶

Sets whether the session should prompt before closing.

Parameters: value (bool) – A bool

set_reduce_flicker(value: bool)¶

Sets whether the flicker fixer is on.

Parameters: value (bool) – A bool

set_right_option_key_changeable(value: bool)¶

Sets whether apps should be able to change the right option key to send esc+.

The values gives whether it should be allowed.

Parameters: value (bool) – A bool

set_right_option_key_sends(value: iterm2.profile.OptionKeySends)¶

Sets the behavior of the right option key.

Parameters: value (OptionKeySends) – An OptionKeySends

set_scrollback_in_alternate_screen(value: bool)¶

Sets whether text gets appended to scrollback in alternate screen mode.

Parameters: value (bool) – A bool

set_scrollback_lines(value: int)¶

Sets the number of scrollback lines.

Value must be at least 0.

Parameters: value (int) – An int

set_scrollback_with_status_bar(value: bool)¶

Sets whether text gets appended to scrollback when there is an app status bar

Parameters: value (bool) – A bool

set_selected_text_color(value: iterm2.color.Color)¶

Sets the selection text color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_selection_color(value: iterm2.color.Color)¶

Sets the selection background color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_semantic_history(value: Dict[str, Any])¶

Sets the semantic history prefs.

Parameters: value – A typing.Dict[str, typing.Any]

set_send_bell_alert(value: bool)¶

Sets whether notifications should be shown for the bell ringing

Parameters: value (bool) – A bool

set_send_code_when_idle(value: bool)¶

Sets whether to send a code when idle

Parameters: value (bool) – A bool

set_send_idle_alert(value: bool)¶

Sets whether notifications should be shown for becoming idle

Parameters: value (bool) – A bool

set_send_new_output_alert(value: bool)¶

Sets whether notifications should be shown for new output

Parameters: value (bool) – A bool

set_send_session_ended_alert(value: bool)¶

Sets whether notifications should be shown for a session ending

Parameters: value (bool) – A bool

set_send_terminal_generated_alerts(value: bool)¶

Sets whether notifications should be shown for escape-sequence originated notifications

Parameters: value (bool) – A bool

set_session_close_undo_timeout(value: float)¶

Sets the amount of time you can undo closing a session

The value is at least 0.

Parameters: value (float) – A float

set_show_mark_indicators(value: bool)¶

Sets whether mark indicators should be visible

Parameters: value (bool) – A bool

set_silence_bell(value: bool)¶

Sets whether the bell makes noise.

Parameters: value (bool) – A bool

set_smart_cursor_color(value: bool)¶

Sets whether to use smart cursor color. This only applies to box cursors. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (bool) – A bool

set_smart_selection_rules(value: List[Dict[str, Any]])¶

Sets the smart selection rules.

The value is a list of dicts of smart selection rules (currently undocumented)

Parameters: value – A typing.List[typing.Dict[str, typing.Any]]

set_status_bar_enabled(value: bool)¶

Sets whether the status bar be enabled.

If True, the status bar will be shown.

Parameters: value (bool) – A bool

set_sync_title(value: bool)¶

Sets whether the profile name stays in the tab title, even if changed by an escape sequence.

Parameters: value (bool) – A bool

set_tab_color(value: iterm2.color.Color)¶

Sets the tab color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A Color

set_thin_strokes(value: iterm2.profile.ThinStrokes)¶

Sets whether thin strokes are used.

Parameters: value (ThinStrokes) – A ThinStrokes

set_title_components(value: List[iterm2.profile.TitleComponents])¶

Sets which components are visible in the session’s title, or selects a custom component.

If it is set to CUSTOM then the title_function must be set properly.

set_title_function(display_name: str, identifier: str)¶

Sets the function call for the session title provider and its display name for the UI.

Parameters: display_name (str) – This is shown in the Title Components menu in the UI.
Identifier: The unique identifier, typically a backwards domain name.

This takes effect only when the title_components property is set to CUSTOM.

set_touchbar_mappings(value: Dict[str, Any])¶

Sets the touchbar actions.

The value is a Dictionary mapping touch bar item to action

Parameters: value – A typing.Dict[str, typing.Any]

set_transparency(value: float)¶

Sets the level of transparency.

The value is between 0 and 1.

Parameters: value (float) – A float

set_triggers(value: List[Dict[str, Any]])¶

Sets the triggers.

Value is an encoded trigger. Use iterm2.decode_trigger to convert from an encoded trigger to an object. Trigger objects can be encoded using the encode property.

Parameters: value – A typing.List[typing.Dict[str, typing.Any]]

set_triggers_use_interpolated_strings(value: bool)¶

Sets whether trigger parameters should be interpreted as interpolated strings.

Parameters: value (bool) – A bool

set_underline_color(value: Optional[iterm2.color.Color])¶

Sets the underline color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value – A typing.Optional[‘iterm2.color.Color’]

set_unicode_normalization(value: iterm2.profile.UnicodeNormalization)¶

Sets the unicode normalization form to use

Parameters: value (UnicodeNormalization) – An UnicodeNormalization

set_unicode_version(value: bool)¶

Sets the unicode version for wcwidth

Parameters: value (bool) – A bool

set_unlimited_scrollback(value: bool)¶

Sets whether the scrollback buffer’s length is unlimited.

Parameters: value (bool) – A bool

set_use_bold_font(value: bool)¶

Sets whether to use the bold variant of the font for bold text.

Parameters: value (bool) – A bool

set_use_bright_bold(value: bool)¶

Sets how bold text is rendered. This is used only when separate light/dark mode colors are not enabled.

This function is deprecated because its behavior changed in iTerm2 version 3.3.7.

Pre-3.3.7, when enabled: * Use the profile-specified bold color for default-colored

bold text.

Dark ANSI colors get replaced with their light counterparts for bold text.

In 3.3.7 and later: * Use the profile-specified bold color for default-colored

bold text.

Use use_bold_color and brighten_bold_text in 3.3.7 and later instead of this method.

Parameters: value (bool) – A bool

set_use_built_in_powerline_glyphs(value: bool)¶

Sets whether powerline glyphs should be drawn by iTerm2 or left to the font.

Parameters: value (bool) – A bool

set_use_csi_u(value: bool)¶

Sets whether to report keystrokes with CSI u protocol.

If True, CSI u will be enabled.

Parameters: value (bool) – A bool

set_use_cursor_guide(value: bool)¶

Sets whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (bool) – A bool

set_use_custom_command(value: str)¶

Sets whether to use a custom command when the session is created.

The value is the string Yes or No

Parameters: value (str) – A str

set_use_custom_window_title(value: bool)¶

Sets whether the custom window title is used.

Should the custom window title in the profile be used?

Parameters: value (bool) – A bool

set_use_italic_font(value: bool)¶

Sets whether italic text is allowed.

Parameters: value (bool) – A bool

set_use_non_ascii_font(value: bool)¶

Sets whether to use a different font for non-ASCII text.

Parameters: value (bool) – A bool

set_use_tab_color(value: bool)¶

Sets whether the tab color should be used. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (bool) – A bool

set_use_transparency_initially(value: bool)¶

Sets whether a window created with this profile respect the transparency setting.

If True, use transparency; if False, force the window to be opaque (but it can be toggled with View > Use Transparency).

Parameters: value (bool) – A bool

set_use_underline_color(value: bool)¶

Sets whether to use the specified underline color. This is used only when separate light/dark mode colors are not enabled.

Parameters: value (bool) – A bool

set_vertical_spacing(value: float)¶

Sets the fraction of vertical spacing. Must be non-negative.

Parameters: value (float) – A float

set_visual_bell(value: bool)¶

Sets whether a bell should be shown when the bell rings

Parameters: value (bool) – A bool

class PartialProfile(session_id, connection, profile_property_list)¶

Represents a profile that has only a subset of fields available for reading.

async async_get_full_profile() → iterm2.profile.Profile ¶

Requests a full profile and returns it.

Raises BadGUIDException if the Guid is not set or does not match a profile.

Returns: A Profile.

async async_make_default()¶: Makes this profile the default profile.

async static async_query(connection: iterm2.connection.Connection, guids: Optional[List[str]] = None, properties: List[str] = ['Guid', 'Name']) → List[iterm2.profile.PartialProfile]¶

Fetches a list of profiles by guid, populating the requested properties.

Parameters

connection (Connection) – The connection to send the query to.
properties – Lists the properties to fetch. Pass None for all. If you wish to fetch the full profile later, you must ensure the ‘Guid’ property is fetched.
guids – Lists GUIDs to list. Pass None for all profiles.

Returns

A list of PartialProfile objects with only the specified properties set.

See also

Example “Change Color Presets On Theme Change”
Example “Change Color Preset by Time of Day”

class BackgroundImageMode(value)¶

Describes how the background image should be accommodated to fit the window.

ASPECT_FILL = 2¶: Scale to fill the space, cropping if needed. Does not distort.

ASPECT_FIT = 3¶: Scale to fit the space, adding letterboxes or pillarboxes if needed. Does not distort.

STRETCH = 0¶: Stretch to fit

TILE = 1¶: Full size, undistorted, and tessellated if needed.

toJSON()¶

class CursorType(value)¶

Describes the type of the cursor.

CURSOR_TYPE_BOX = 2¶: Box cursor

CURSOR_TYPE_UNDERLINE = 0¶: Underline cursor

CURSOR_TYPE_VERTICAL = 1¶: Vertical bar cursor

class ThinStrokes(value)¶

When thin strokes should be used.

THIN_STROKES_SETTING_ALWAYS = 3¶: Always.

THIN_STROKES_SETTING_DARK_BACKGROUNDS_ONLY = 2¶: When the background is dark.

THIN_STROKES_SETTING_NEVER = 0¶: NEver

THIN_STROKES_SETTING_RETINA_DARK_BACKGROUNDS_ONLY = 1¶: When the background is dark and the display is a retina display.

THIN_STROKES_SETTING_RETINA_ONLY = 4¶: When the display is a retina display.

class UnicodeNormalization(value)¶

How to perform Unicode normalization.

UNICODE_NORMALIZATION_HFSPLUS = 3¶: Apple’s HFS+ normalization form

UNICODE_NORMALIZATION_NFC = 1¶: Normalization form C

UNICODE_NORMALIZATION_NFD = 2¶: Normalization form D

UNICODE_NORMALIZATION_NONE = 0¶: Do not modify input

class CharacterEncoding(value)¶: String encodings.

class OptionKeySends(value)¶

How should the option key behave?

OPTION_KEY_ESC = 2¶: Adds ESC prefix.

OPTION_KEY_META = 1¶: Acts like Meta. Not recommended.

OPTION_KEY_NORMAL = 0¶: Standard behavior

class InitialWorkingDirectory(value)¶

How should the initial working directory of a session be set?

INITIAL_WORKING_DIRECTORY_ADVANCED = 'Advanced'¶: Use advanced settings, which specify more granular behavior depending on whether the new session is a new window, tab, or split pane.

INITIAL_WORKING_DIRECTORY_CUSTOM = 'Yes'¶: Custom directory, specified elsewhere

INITIAL_WORKING_DIRECTORY_HOME = 'No'¶: Use default of home directory

INITIAL_WORKING_DIRECTORY_RECYCLE = 'Recycle'¶: Reuse the “current” directory, or home if there is no current.

Profile¶

Indices and tables¶