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.

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