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.

See also

Example “Modify Background Image Blending

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

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

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

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.

See also

Example “Modify Background Image Blending

Returns:

A float

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

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

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

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.

See also

Example “Modify Background Image Blending

Parameters:

value (float) – A float

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

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

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.

See also

Example “Change Color Presets On Theme Change”

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

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.

Indices and tables