Configuring Contour

Contour offers a wide range of configuration options that can be customized, including color scheme, shell, initial working directory, and more. The configuration options can be categorized into several groups:

Global options: These settings determine the overall behavior of the terminal and apply to all profiles.
Profiles: With profiles, you can configure the terminal more granularly and create multiple profiles that can be easily switched between.
Color scheme: Contour allows you to define different color schemes for the terminal and choose which one to use for each of the profiles.

On Unix systems, the main configuration file is located at ~/.config/contour/contour.yml and is both read from and auto-generated there. On Windows systems, the file is located at %LocalAppData%\contour\contour.yml.

Please note that on Unix systems, the environment variable XDG_CONFIG_HOME (by default set to ~/.config) is taken into account.

By default, on Unix systems, Contour is executed with the following arguments contour config ~/.config/contour/contour.yml profile main. If the configuration file includes a default_profile variable, it will be used as the default profile. Otherwise, the first profile listed in the file will be the default one.

How to

Load specific configuration file

contour config /path/to/file/with/configuration.yml

Set profile for current session

you can utilize the profile parameter with the contour command
contour profile one_of_profiles

Global options

Let's go through the different sections of the global configurations in the file:

`platform_plugin`

option allows you to override the auto-detected platform plugin to be loaded. You can specify values like auto, xcb, cocoa, direct2d, or winrt to determine the platform plugin. The default value is auto.

`renderer`

section contains configuration options related to the VT Renderer, which is responsible for rendering the terminal onto the screen. It includes the backend option to specify the Qt RHI graphics API, with possible values of auto (the native backend per platform), OpenGL, vulkan, direct3d11, direct3d12, metal, or software. The other options in this section control the tile mapping and caching for performance optimization.

`word_delimiters`

option defines the delimiters to be used when selecting words in the terminal. It is a string of characters that act as delimiters.

`extended_word_delimiters`

option defines the delimiters to be used when selecting words in the second time. It is a string of characters that act as delimiters. By default word delimiters are used.

`command_palette_recent_count`

option sets how many recently used commands the command palette pins above its alphabetical list. The palette is opened with the OpenCommandPalette action (bound to Ctrl+Shift+P by default), and the list of recent commands is remembered across restarts in the command-history.yml file beside your configuration file. Set it to 0 to turn the "recently used" section off entirely. The default value is 5.

`pty_read_buffer_size`

option specifies the default PTY read buffer size in bytes. It is an advanced option and should be used with caution. The default value is 16384.

`pty_buffer_object_size`

option sets the size in bytes per PTY Buffer Object. It is an advanced option for internal storage and should be changed carefully. The default value is 1048576.

`default_profile_name`

option determines the default profile to use in the terminal.

`early_exit_threshold`

option determines the early threshold time. If contour attempts to close earlier than specified threshold, additional message will be printed that contour terminated too early and additional key press is required to close contour.

`spawn_new_process`

flag determines whether a new process should be spawned when creating a new terminal. The default value is false.

`reflow_on_resize`

option controls whether or not the lines in the terminal should be reflowed when a resize event occurs. The default value is true.

`tab_switch_on_horizontal_wheel`

option controls whether a horizontal mouse wheel tilt (or a horizontal trackpad swipe) over the tab strip or the terminal switches to the previous/next tab. An application that has requested mouse reporting keeps receiving the horizontal wheel; holding the bypass modifier switches tabs anyway. An explicit WheelLeft/WheelRight entry in input_mapping takes precedence. The default value is true.

`hyperlink_hover_tooltip`

Whether hovering an OSC 8 hyperlink shows a tooltip naming its target, so it can be read before it is followed. A local file:// target is shown as a plain path.

`progress_timeout`

How long an application's progress indicator (OSC 9;4) stays on screen without being updated, in milliseconds.

0 (the default) disables expiry entirely: the indicator persists until the application clears it with state 0, which is what the sequence specifies and what ConEmu and Windows Terminal do. The terminal cannot tell a long-running operation from an application that died holding one, so a non-zero value trades that fidelity for a guard against a bar left stranded on screen. Applications using the protocol are expected to refresh it about once a second, so a timeout well above that -- 15000 or so -- is the useful range.

`notification_close_timeout`

How long after showing a desktop notification the terminal waits before assuming the desktop closed it, in milliseconds.

This only applies where a close cannot be observed. Contour normally learns that a notification was dismissed or expired from the desktop itself and reports it back to the application as the OSC 99 p=close event. Inside a Flatpak sandbox that is impossible: the only reachable service is the org.freedesktop.portal.Notification portal, which has no close signal of any kind, so an application that asked for close events (c=1) would otherwise wait forever.

A notification that states its own lifetime through w= is answered after that instead -- the application already said what it wanted. Only w=-1, "whatever the desktop does", falls back to this value.

Two cases are deliberately never answered, because there is no moment at which an answer would be true: 0 here, which disables the assumption outright, and w=0 on the notification, which asks for a popup that never expires on its own. An application that requested close events in either case is not told.

Read once per terminal session, so a changed value reaches sessions opened after the reload.

Because the report is a timer rather than an observation, it is marked untracked on the wire, so an application can tell the two apart.

`accessibility_announcements`

Whether events with no representation in the accessibility tree -- the bell, a desktop notification, a mode change -- are announced to assistive technology. Costs nothing while no assistive client is attached. See Accessibility.

`accessibility_caret_reporting`

Whether the terminal reports where the caret is to assistive technology, which is how a screen magnifier follows what you are typing. Costs nothing while no assistive client is attached. Turn it off to rule the caret reports out when diagnosing input latency. See Accessibility.

`tab_bar_position`

Selects where the GUI tab strip (tab bar) is placed within the window. Valid values (ignore-case):

Top — the tab strip is drawn above the terminal content. This is the default.
Bottom — the tab strip is drawn below the terminal content.

`tab_bar_visibility`

Selects when the GUI tab strip (tab bar) is shown. Valid values (ignore-case):

Always — the tab strip is always shown. This is the default.
Never — the tab strip is never shown.
Multiple — the tab strip is shown only when the window has more than one tab, and hidden while a single tab remains.

`gui_config_locked`

flag, when true, opens the in-app settings page read-only and prevents the GUI from writing any of its side files (profiles/, colorschemes/, settings.yml), so this hand-maintained configuration file stays the single source of truth. The default value is false.

`theme`

option selects the light/dark appearance of the GUI chrome (title bar, tab strip, command palette, settings pages, dialogs) independently of the operating system. Possible values are system (follow the OS color scheme), dark, and light. The terminal grid keeps following the OS light/dark preference through its own color scheme. The default value is system.

`ui_style`

Selects how the application's own chrome is painted: the tab strip and title bar, and the controls (buttons, fields, menu entries, combo boxes) inside menus, popups and the settings page. This selects a shape, not a color: both styles take their colors from the operating system palette and follow the theme setting. Valid values (ignore-case):

native — platform-native GUI chrome. This is the default.
terminal — the chrome is quantized to whole character cells of a monospace font and its corners are squared off, so the window reads as one continuous TUI rather than as a GUI wrapped around a terminal. Tabs keep every GUI affordance (drag to reorder, tear off, rename, close, context menu); only their appearance changes.

This is the recommended way to get the terminal look now that a window can hold split panes: the indicator status line's {Tabs} item still works, but it is drawn per pane, so a split window would show one tab list per pane instead of one per window.

The Qt Quick Controls half of the style is selected once, before the first control is created, so a change takes effect on the next start rather than live.

`window_control_style`

Selects how the window's own minimize/maximize/close controls are drawn, and which side of the tab bar they sit on. These are drawn only while the native title bar is hidden (show_title_bar is false, the default), which is when the tab bar doubles as the title bar; with the native frame shown, the operating system draws them itself. Valid values (ignore-case):

auto — match the host: macOS gets macos, Windows gets windows, a KDE Plasma session gets plasma, and anything else gets windows. This is the default.
windows — trailing (right) edge, flush rectangular buttons in minimize/maximize/close order, with a red close hover.
macos — leading (left) edge, traffic lights in close/minimize/zoom order. The dots reveal their glyphs while the group is hovered and grey out while the window is inactive.
plasma — trailing (right) edge, like windows but with the circular hover fills of KDE Plasma's Breeze decoration.

Independent of ui_style: every value works in both the native and the terminal chrome, and takes its extents from whichever of those is active — so under ui_style: terminal the controls stay quantized to whole character cells, and the traffic lights are drawn as coloured cell-wide dots.

Unlike ui_style, this applies immediately when changed from the settings page.

`ui_font_family`

Font family the terminal-style chrome is drawn with. When empty (the default) the chrome inherits the regular font family of the profile the window is running (-p/--profile, else default_profile), which is what makes it match the terminal grid below it. Ignored while ui_style is native, where the chrome uses the platform UI font. Takes effect on the next start.

`ui_font_size`

Font size, in points, the terminal-style chrome is drawn with. When 0 (the default) the chrome inherits the font size of the profile the window is running. Ignored while ui_style is native. Takes effect on the next start.

`grapheme_clustering`

Whether DEC mode 2027 starts out set. While set, a late codepoint may widen its grapheme cluster -- U+FE0F widens a cluster to two columns -- but a cluster never narrows again. While unset, a cell is measured by plain wcwidth() with no clustering. Applications may still toggle the mode at runtime.

`text_scaling_method`

How a glyph is enlarged for scaled text (kitty text sizing protocol, OSC 66). stretch magnifies the ordinary-size glyph: free to rasterize, no extra atlas entries, but softer at large scales. rerasterize asks the font for the glyph at the larger size: crisp at any scale, at the cost of a rasterization and an atlas entry per glyph and scale.

`bypass_mouse_protocol_modifiers`

option specifies the keyboard modifier (e.g., Shift) that can be used to bypass the terminal's mouse protocol and select screen content.

`mouse_block_selection_modifiers`

option determines the modifier (e.g., Control) that needs to be pressed to initiate block selection using the left mouse button.

`on_mouse_selection`

option selects the action to perform when a text selection has been made. Possible values include None, CopyToClipboard, and CopyToSelectionClipboard.

`live`

option determines whether the instance should reload the configuration files whenever they change. The default value is false.

`experimental_features`

`images`

section contains configuration options related to inline images. It includes options like sixel_scrolling, sixel_register_count, and good_image_protocol to control various aspects of image rendering. The maximum image size is derived from the screen size; max_width and max_height are deprecated and ignored.

`folding`

configuration controls output folding: collapsing a finished command's output down to the prompt line it was entered at, and expanding it again.

folding:
  enabled: true
  show_markers: true
  auto_collapse_on_new_command: false
  on_jump_into_fold: expand

Folding is driven entirely by the OSC 133 semantic marks a shell with shell integration emits, so no additional escape sequence is involved and any shell that already speaks OSC 133 works. Only FINISHED commands fold, which is why the prompt you are typing at never does. enabled Whether folding is available at all. When false the actions below do nothing and no gutter is reserved.
show_markers Whether to reserve a one-column gutter to the left of the grid and draw a fold column in it: a boxed minus on a foldable prompt line whose output is showing, a boxed plus once it is collapsed, and a bar down the side of the block joining the two. Clicking anywhere on that column toggles the fold. Note that the gutter costs one column of terminal width.
auto_collapse_on_new_command Whether a command's output is collapsed automatically as soon as the next prompt appears, so that only the command you are running now is shown in full.
on_jump_into_fold What a Vi-mode jump that targets a line inside a collapsed block does: expand opens the block so the cursor lands on what it was aiming at, skip leaves it collapsed and stops at its prompt line instead. Plain motions (j, k, {, }, ++ctrl+d++, ++ctrl+u++) always step over a collapsed block regardless of this setting.

The actions CollapseAllFolds, ExpandAllFolds, CollapseLastFold, ToggleLastFold and ToggleFold can be bound to keys; ScrollMarkUp and ScrollMarkDown already move the viewport from one prompt to the next.

`osc_context`

configuration controls whether Contour reads OSC 3008, systemd's hierarchical context signalling (UAPI.15): the nested stack of contexts a shell, run0, ssh or a container runtime opens around whatever runs inside it.

osc_context:
  enabled: true
  max_depth: 16
  max_retained_contexts: 256
  derive_markers: when_alone
  tinting: boundaries

systemd 258 and later ship a shell snippet that emits these sequences around every interactive command with no configuration at all, so on such a system Contour learns command boundaries, exit statuses (including whether a command crashed or was interrupted, which OSC 133 cannot express) and working directories without any shell integration being installed. enabled Whether the sequences are read at all. When false nothing is tracked, nothing is derived and nothing is tinted.
max_depth How deep the context stack may grow. Beyond it, further contexts are ignored -- the NEWER ones, so that a program cannot push the context established above it out of the stack.
max_retained_contexts How many contexts are remembered for scrolled-back output that still refers to them. Older ones are forgotten, and output belonging to them simply stops being attributed.
derive_markers Whether OSC 3008 may stand in for a shell integration that is not installed. when_alone derives prompt and command marks from it only while OSC 133 has said nothing; once a shell integration speaks, it owns the marks for the rest of the session. never leaves marks entirely to OSC 133.
tinting Which contexts may tint the page background. The colours themselves come from the colour scheme's tint: map, which no shipped scheme sets, so nothing is tinted until you choose a colour there. Note that a context is something the session announced: anything that can write to your terminal can announce one, or fail to announce one, so the absence of a tint is not a statement that nothing is elevated.

`default_layout_name`

Name of the layout to open at startup, instead of a single default tab.

`git_drawings`

fmt formatted doc thin

`box_arc_style`

fmt formatted doc round

`braille_style`

fmt formatted doc circle

Default global parameters

platform_plugin: auto
renderer:
    backend: auto
    tile_hashtable_slots: 4096
    tile_cache_count: 4000
    tile_direct_mapping: true
word_delimiters: " /\\()\"'-.,:;<>~!@#$%^&*+=[]{}~?|│"
read_buffer_size: 16384
pty_buffer_size: 1048576
default_profile: main
spawn_new_process: false
reflow_on_resize: true
bypass_mouse_protocol_modifier: Shift
mouse_block_selection_modifier: Control
on_mouse_select: CopyToSelectionClipboard
live_config: false
images:
    sixel_scrolling: true
    sixel_register_count: 4096

The default profile is automatically the top (first) defined profile in the configuration file, but can be explicitly set to an order-independent name using default_profile configuration key.

Profiles

Profiles is the main part of user specific customizations, you can create more than one profile and chose which you want to use during startup or define in configuration file.

By default each profile inherites values from default_profile. This means that you can specify only values that you want to change in respect to default profile, for example you can create new profile to use bash as a shell preserving other configuration from main profile

profiles:
    main:
    # default profile here
    bash:
        shell: "/usr/bin/bash"

For the full list of options see generated configuration file on your system or Profiles section of documentation.

Color Schemes

In contour you can specify different colors inside terminal, for example text background and foreground, cursor properties, selection colors and plenty others. You can configure your color profiles, whereas a color can be expressed in standard web format, with a leading # followed by red/green/blue values, 7 characters in total. You may alternatively use 0x as prefix instead of #. For example 0x102030 is equal to '#102030'.

Syntax for color schemes repeat the one of profiles. First color scheme inside configuration file must be named default, each other color schemes inherit values from default color scheme. Example of configuration for color_schemes

color_schemes:
    default:
    # values for default color scheme
    different_selection:
      selection:
        background: '#fff0f0'

For the full list of options see generated configuration file on your system or Colors section of documentation.