language = de
    

will force the strings in Ghostty’s graphical user interface to be in German rather than the system default.

This will not affect the language used by programs run within Ghostty. Those will continue to use the default system language. There are also many non-GUI elements in Ghostty that are not translated - this setting will have no effect on those.

Warning: This setting cannot be reloaded at runtime. To change the language you must fully restart Ghostty.

GTK only. Available since 1.3.0.

You can generate the list of valid values using the CLI:

ghostty +list-fonts
    

This configuration can be repeated multiple times to specify preferred fallback fonts when the requested codepoint is not available in the primary font. This is particularly useful for multiple languages, symbolic fonts, etc.

Notes on emoji specifically: On macOS, Ghostty by default will always use Apple Color Emoji and on Linux will always use Noto Emoji. You can override this behavior by specifying a font family here that contains emoji glyphs.

The specific styles (bold, italic, bold italic) do not need to be explicitly set. If a style is not set, then the regular style (font-family) will be searched for stylistic variants. If a stylistic variant is not found, Ghostty will use the regular style. This prevents falling back to a different font family just to get a style such as bold. This also applies if you explicitly specify a font family for a style. For example, if you set font-family-bold = FooBar and “FooBar” cannot be found, Ghostty will use whatever font is set for font-family for the bold style.

Finally, some styles may be synthesized if they are not supported. For example, if a font does not have an italic style and no alternative italic font is specified, Ghostty will synthesize an italic style by applying a slant to the regular style. If you want to disable these synthesized styles then you can use the font-style configurations as documented below.

You can disable styles completely by using the font-style set of configurations. See the documentation for font-style for more information.

If you want to overwrite a previous set value rather than append a fallback, specify the value as "" (empty string) to reset the list and then set the new values. For example:

font-family = ""
font-family = "My Favorite Font"
    

Setting any of these as CLI arguments will automatically clear the values set in configuration files so you don’t need to specify --font-family="" before setting a new value. You only need to specify this within config files if you want to clear previously set values in configuration files or on the CLI if you want to clear values set on the

You can also use these fields to completely disable a font style. If you set the value of the configuration below to literal false then that font style will be disabled. If the running program in the terminal requests a disabled font style, the regular font style will be used instead.

These are only valid if its corresponding font-family is also specified. If no font-family is specified, then the font-style is ignored unless you’re disabling the font style.

Ghostty can synthesize bold, italic, and bold italic styles if the font does not have a specific style. For bold, this is done by drawing an outline around the glyph of varying thickness. For italic, this is done by applying a slant to the glyph. For bold italic, both of these are applied.

Synthetic styles are not perfect and will generally not look as good as a font that has the style natively. However, they are useful to provide styled text when the font does not have the style.

Set this to “false” or “true” to disable or enable synthetic styles completely. You can disable specific styles using “no-bold”, “no-italic”, and “no-bold-italic”. You can disable multiple styles by separating them with a comma. For example, “no-bold,no-italic”.

Available style keys are: bold, italic, bold-italic.

If synthetic styles are disabled, then the regular style will be used instead if the requested style is not available. If the font has the requested style, then the font will be used as-is since the style is not synthetic.

Warning: An easy mistake is to disable bold or italic but not bold-italic. Disabling only bold or italic will NOT disable either in the bold-italic style. If you want to disable bold-italic, you must explicitly disable it. You cannot partially disable bold-italic.

By default, synthetic styles are enabled.

The syntax for feature settings is as follows, where feat is a feature:

• Enable features with e.g. feat, +feat, feat on, feat=1.
• Disabled features with e.g. -feat, feat off, feat=0.
• Set a feature value with e.g. feat=2, feat = 3, feat 4.
• Feature names may be wrapped in quotes, meaning this config should be syntactically compatible with the font-feature-settings CSS property.

The syntax is fairly loose, but invalid settings will be silently ignored.

The font feature will apply to all fonts rendered by Ghostty. A future enhancement will allow targeting specific faces.

To disable programming ligatures, use -calt since this is the typical feature name for programming ligatures. To look into what font features your font has and what they do, use a font inspection tool such as fontdrop.info.

To generally disable most ligatures, use -calt, -liga, -dlig.

For example, 13.5pt @ 2px/pt = 27px

Changing this configuration at runtime will only affect existing terminals that have NOT manually adjusted their font size in some way (e.g. increased or decreased the font size). Terminals that have manually adjusted their font size will retain their manually adjusted size. Otherwise, the font size of existing terminals will be updated on reload.

On Linux with GTK, font size is scaled according to both display-wide and text-specific scaling factors, which are often managed by your desktop environment (e.g. the GNOME display scale and large text settings).

The format of this is id=value where id is the axis identifier. An axis identifier is always a 4 character string, such as wght. To get the list of supported axes, look at your font documentation or use a font inspection tool.

Invalid ids and values are usually ignored. For example, if a font only supports weights from 100 to 700, setting wght=800 will do nothing (it will not be clamped to 700). You must consult your font’s documentation to see what values are supported.

Common axes are: wght (weight), slnt (slant), ital (italic), opsz (optical size), wdth (width), GRAD (gradient), etc.

The syntax is codepoint=fontname where codepoint is either a single codepoint or a range. Codepoints must be specified as full Unicode hex values, such as U+ABCD. Codepoints ranges are specified as U+ABCD-U+DEFG. You can specify multiple ranges for the same font separated by commas, such as U+ABCD-U+DEFG,U+1234-U+5678=fontname. The font name is the same value as you would use for font-family.

This configuration can be repeated multiple times to specify multiple codepoint mappings.

Changing this configuration at runtime will only affect new terminals, i.e. new windows, tabs, etc.

This configuration allows you to replace specific Unicode characters with other characters or strings when copying terminal content to the clipboard. This is useful for converting special terminal symbols to more compatible characters for pasting into other applications. The syntax is similar to font-codepoint-map:

• Single codepoint: U+1234=U+ABCD or U+1234=replacement_text
• Codepoint range: U+1234-U+5678=U+ABCD Examples:
• clipboard-codepoint-map = U+2500=U+002D (box drawing horizontal → hyphen)
• clipboard-codepoint-map = U+2502=U+007C (box drawing vertical → pipe)
• clipboard-codepoint-map = U+03A3=SUM (Greek sigma → “SUM”)

This configuration can be repeated multiple times to specify multiple mappings. Later entries take priority over earlier ones for overlapping ranges.

Note: This only applies to text copying operations, not URL copying.

Valid values are integers between 0 and 255. 0 does not correspond to no thickening, rather it corresponds to the lightest available thickening.

Has no effect when font-thicken is set to false.

This is currently only supported on macOS.

A “run” is a contiguous segment of text that is shaped together. “Shaping” is the process of converting text (codepoints) into glyphs (renderable characters). This is how ligatures are formed, among other things. For example, if a coding font turns “!=” into a single glyph, then it must see “!” and “=” next to each other in a single run. When a run is broken, the text is shaped separately. To continue our example, if “!” is at the end of one run and “=” is at the start of the next run, then the ligature will not be formed.

Ghostty breaks runs at certain points to improve readability or usability. For example, Ghostty by default will break runs under the cursor so that text editing can see the individual characters rather than a ligature. This configuration lets you configure this behavior.

Combine values with a comma to set multiple options. Prefix an option with “no-” to disable it. Enabling and disabling options can be done at the same time.

Available options:

•

cursor - Break runs under the cursor.

Available since: 1.2.0

This affects the appearance of text and of any images with transparency. Additionally, custom shaders will receive colors in the configured space.

On macOS the default is native, on all other platforms the default is linear-corrected.

Valid values:

• native - Perform alpha blending in the native color space for the OS. On macOS this corresponds to Display P3, and on Linux it’s sRGB.
• linear - Perform alpha blending in linear space. This will eliminate the darkening artifacts around the edges of text that are very visible when certain color combinations are used (e.g. red / green), but makes dark text look much thinner than normal and light text much thicker. This is also sometimes known as “gamma correction”.
• linear-corrected - Same as linear, but with a correction step applied for text that makes it look nearly or completely identical to native, but without any of the darkening artifacts.

Available since: 1.1.0

For example, a value of 1 increases the value by 1; it does not set it to literally 1. A value of 20% increases the value by 20%. And so on.

There is little to no validation on these values so the wrong values (e.g. -100%) can cause the terminal to be unusable. Use with caution and reason.

Some values are clamped to minimum or maximum values. This can make it appear that certain values are ignored. For example, many *-thickness adjustments cannot go below 1px.

adjust-cell-height has some additional behaviors to describe:

• The font will be centered vertically in the cell.
• The cursor will remain the same size as the font, but may be adjusted separately with adjust-cursor-height.
• Powerline glyphs will be adjusted along with the cell height so that things like status lines continue to look aligned.

A positive (negative) value will increase (decrease) the maximum icon height. This may not affect all icons equally: the effect depends on whether the default size of the icon is height-constrained, which in turn depends on the aspect ratio of both the icon and your primary font.

Certain icons designed for box drawing and terminal graphics, such as Powerline symbols, are not affected by this option.

See the notes about adjustments in adjust-cell-width.

Available in: 1.2.0

Valid values are:

•

legacy - Use a legacy method to determine grapheme width, such as wcswidth This maximizes compatibility with legacy programs but may result in incorrect grapheme width for certain graphemes such as skin-tone emoji, non-English characters, etc.

•

unicode - Use the Unicode standard to determine grapheme width.

If a running program explicitly enables terminal mode 2027, then unicode width will be forced regardless of this configuration. When mode 2027 is reset, this configuration will be used again.

This configuration can be changed at runtime but will not affect existing terminals. Only new terminals will use the new configuration.

This configuration only applies to Ghostty builds that use FreeType. This is usually the case only for Linux builds. macOS uses CoreText and does not have an equivalent configuration.

Available flags:

• hinting - Enable or disable hinting. Enabled by default.
• force-autohint - Always use the freetype auto-hinter instead of the font’s native hinter. Disabled by default.
• monochrome - Instructs renderer to use 1-bit monochrome rendering. This will disable anti-aliasing, and probably not look very good unless you’re using a pixel font. Disabled by default.
• autohint - Enable the freetype auto-hinter. Enabled by default.
• light - Use a light hinting style, better preserving glyph shapes. This is the most common setting in GTK apps and therefore also Ghostty’s default. This has no effect if monochrome is enabled. Enabled by default.

Example: hinting, no-hinting, force-autohint, no-force-autohint

If the theme is an absolute pathname, Ghostty will attempt to load that file as a theme. If that file does not exist or is inaccessible, an error will be logged and no other directories will be searched.

If the theme is not an absolute pathname, two different directories will be searched for a file name that matches the theme. This is case sensitive on systems with case-sensitive filesystems. It is an error for a theme name to include path separators unless it is an absolute pathname.

The first directory is the themes subdirectory of your Ghostty configuration directory. This is $XDG_CONFIG_HOME/ghostty/themes or ~/.config/ghostty/themes.

The second directory is the themes subdirectory of the Ghostty resources directory. Ghostty ships with a multitude of themes that will be installed into this directory. On macOS, this list is in the Ghostty.app/Contents/Resources/ghostty/themes directory. On Linux, this list is in the share/ghostty/themes directory (wherever you installed the Ghostty “share” directory.

To see a list of available themes, run ghostty +list-themes.

A theme file is simply another Ghostty configuration file. They share the same syntax and same configuration options. A theme can set any valid configuration option so please do not use a theme file from an untrusted source. The built-in themes are audited to only set safe configuration options.

Some options cannot be set within theme files. The reason these are not supported should be self-evident. A theme file cannot set theme or config-file. At the time of writing this, Ghostty will not show any warnings or errors if you set these options in a theme file but they will be silently ignored.

Any additional colors specified via background, foreground, palette, etc. will override the colors specified in the theme.

To specify a different theme for light and dark mode, use the following syntax: light:theme-name,dark:theme-name. For example: light:Rose Pine Dawn,dark:Rose Pine. Whitespace around all values are trimmed and order of light and dark does not matter. Both light and dark must be specified in this form. In this form, the theme used will be based on the current desktop environment theme.

There are some known bugs with light/dark mode theming. These will be fixed in a future update:

•

macOS: titlebar tabs style is not updated when switching themes.

This should be a path to a PNG or JPEG file, other image formats are not yet supported.

The background image is currently per-terminal, not per-window. If you are a heavy split user, the background image will be repeated across splits. A future improvement to Ghostty will address this.

WARNING: Background images are currently duplicated in VRAM per-terminal. For sufficiently large images, this could lead to a large increase in memory usage (specifically VRAM usage). A future Ghostty improvement will resolve this by sharing image textures across terminals.

Available since: 1.2.0

This is relative to the value of background-opacity.

A value of 1.0 (the default) will result in the background image being placed on top of the general background color, and then the combined result will be adjusted to the opacity specified by background-opacity.

A value less than 1.0 will result in the background image being mixed with the general background color before the combined result is adjusted to the configured background-opacity.

A value greater than 1.0 will result in the background image having a higher opacity than the general background color. For instance, if the configured background-opacity is 0.5 and background-image-opacity is set to 1.5, then the final opacity of the background image will be 0.5 * 1.5 = 0.75.

Available since: 1.2.0

• top-left
• top-center
• top-right
• center-left
• center
• center-right
• bottom-left
• bottom-center
• bottom-right

The default value is center.

Available since: 1.2.0

Valid values are:

•

contain

•

cover

•

stretch

•

none

The default value is contain.

Available since: 1.2.0

If this is set to true, the background image will be repeated if there would otherwise be blank space around it because it doesn’t completely fill the terminal area.

The default value is false.

Available since: 1.2.0

“Typing” is specifically defined as any non-modifier (shift, control, alt, etc.) keypress that produces data to be sent to the application running within the terminal (e.g. the shell). Additionally, selection is cleared when any preedit or composition state is started (e.g. when typing languages such as Japanese).

If this is false, then the selection can still be manually cleared by clicking once or by pressing escape.

Available since: 1.2.0

When set to true, the selection will be automatically cleared after any copy operation that invokes the copy_to_clipboard keyboard binding. Importantly, this will not clear the selection if the copy operation was invoked via copy-on-select.

When set to false, the selection remains visible after copying, allowing to see what was copied and potentially perform additional operations on the same selection.

This is similar to the WORDCHARS environment variable in zsh, except this specifies the boundary characters rather than the word characters. The default includes common delimiters and punctuation that typically separate words in code and prose.

Each character in this string becomes a word boundary. Multi-byte UTF-8 characters are supported, but only single codepoints can be specified. Multi-codepoint sequences (e.g. emoji) are not supported.

The null character (U+0000) is always treated as a boundary and does not need to be included in this configuration.

Default: \t'"│`|:;,()[]{}<>$

To add or remove specific characters, you can set this to a custom value. For example, to treat semicolons as part of words:

selection-word-chars = " \t'\"│`|:,()[]{}<>$"
    

Available since: 1.3.0

If you want to avoid invisible text (same color as background), a value of 1.1 is a good value. If you want to avoid text that is difficult to read, a value of 3 or higher is a good value. The higher the value, the more likely that text will become black or white.

This value does not apply to Emoji or images.

The palette index can be in decimal, binary, octal, or hexadecimal. Decimal is assumed unless a prefix is used: 0b for binary, 0o for octal, and 0x for hexadecimal.

For definitions on the color indices and what they canonically map to, see this cheat sheet.

For most themes, you only need to set the first 16 colors (0–15) since the rest of the palette (16–255) will be automatically generated by default (see palette-generate for more details).

This lets theme authors specify only the base 16 colors and have the rest of the palette be automatically generated in a consistent and aesthetic way.

When enabled, the 6×6×6 color cube and 24-step grayscale ramp are derived from interpolations of the base palette, giving a more cohesive look. Colors that have been explicitly set via palette are never overwritten.

The default value is false (disabled), because many legacy programs using the 256-color palette hardcode assumptions about what these colors are (mostly assuming the xterm 256 color palette). However, this is still a very useful tool for theme authors and users who want to customize their palette without having to specify all 256 colors.

For more information on how the generation works, see here: https://gist.github.com/jake-stewart/0a8ea46159a7da2c808e5be2177e1783

Available since: 1.3.0

This defaults to off because some legacy terminal applications hardcode the assumption that palette indices 16–231 are ordered from darkest to lightest, so enabling this would make them unreadable. This is not a generally good assumption and we encourage modern terminal applications to use the indices in a more semantic way.

This has no effect if palette-generate is disabled.

For more information see palette-generate.

Available since: 1.3.0

Direct colors can be specified as either hex (#RRGGBB or RRGGBB) or a named X11 color.

Additionally, special values can be used to set the color to match other colors at runtime:

• cell-foreground - Match the cell foreground color. (Available since: 1.2.0)
• cell-background - Match the cell background color. (Available since: 1.2.0)

Note that shell integration will automatically set the cursor to a bar at a prompt, regardless of this configuration. You can disable that behavior by specifying shell-integration-features = no-cursor or disabling shell integration entirely.

Valid values are:

• block
• bar
• underline
• block_hollow

If this is not set, the cursor blinks by default. Note that this is not the same as a “true” value, as noted below.

If this is not set at all (null), then Ghostty will respect DEC Mode 12 (AT&T cursor blink) as an alternate approach to turning blinking on/off. If this is set to any value other than null, DEC mode 12 will be ignored but DECSCUSR will still be respected.

Valid values are:

• (blank)
• true
• false

This feature requires shell integration, specifically prompt marking via OSC 133. Some shells like Fish (v4) and Nu (0.111+) natively support this while others may require additional configuration or Ghostty’s shell integration features to be enabled.

Depending on the shell, this works either by translating your click position into a series of synthetic arrow key movements or by sending a click event directly to the shell. In either case, some unexpected behavior around edge cases is possible.

Available options:

• keystroke If set, scroll the surface to the bottom when the user presses a key that results in data being sent to the PTY (basically anything but modifiers or keybinds that are processed by Ghostty).
• output If set, scroll the surface to the bottom if there is new data to display (e.g., when new lines are printed to the terminal).

The default is keystroke, no-output.

The default value of false means that the shift key is not sent with the mouse protocol and will extend the selection. This value can be conditionally overridden by the running program with the XTSHIFTESCAPE sequence.

The value true means that the shift key is sent with the mouse protocol but the running program can override this behavior with XTSHIFTESCAPE.

The value never is the same as false but the running program cannot override this behavior with XTSHIFTESCAPE. The value always is the same as true but the running program cannot override this behavior with XTSHIFTESCAPE.

If you always want shift to extend mouse selection even if the program requests otherwise, set this to never.

Valid values are:

• true
• false
• always
• never

When set to true (the default), terminal applications can request mouse reporting and will receive mouse events according to their requested mode.

This can be toggled at runtime using the toggle_mouse_reporting keybind action.

A prefix of precision: or discrete: can be used to set the multiplier only for scrolling with the specific type of devices. These can be comma-separated to set both types of multipliers at the same time, e.g. precision:0.1,discrete:3. If no prefix is used, the multiplier applies to all scrolling devices. Specifying a prefix was introduced in Ghostty 1.2.1.

The value will be clamped to [0.01, 10,000]. Both of these are extreme and you’re likely to have a bad experience if you set either extreme.

The default value is “3” for discrete devices and “1” for precision devices.

On macOS, background opacity is disabled when the terminal enters native fullscreen. This is because the background becomes gray and it can cause widgets to show through which isn’t generally desirable.

On macOS, changing this configuration requires restarting Ghostty completely.

Normally, background-opacity is only applied to the window background. If a cell has an explicit background color set, such as red, then that background color will be fully opaque. An effect of this is that some terminal applications that repaint the background color of the terminal such as a Neovim and Tmux may not respect the background-opacity (by design).

Setting this to true will apply the background-opacity to all cells regardless of whether they have an explicit background color set or not.

Available since: 1.2.0

Valid values are:

• a nonnegative integer specifying the blur intensity
• false, equivalent to a blur intensity of 0
• true, equivalent to the default blur intensity of 20, which is reasonable for a good looking blur. Higher blur intensities may cause strange rendering and performance issues.

On macOS 26.0 and later, there are additional special values that can be set to use the native macOS glass effects:

• macos-glass-regular - Standard glass effect with some opacity
• macos-glass-clear - Highly transparent glass effect

If the macOS values are set, then this implies background-blur = true on non-macOS platforms.

Supported on macOS and on some Linux desktop environments, including:

•

KDE Plasma (Wayland and X11)

Warning: the exact blur intensity is ignored under KDE Plasma, and setting this setting to either true or any positive blur intensity value would achieve the same effect. The reason is that KWin, the window compositor powering Plasma, only has one global blur setting and does not allow applications to specify individual blur settings.

To configure KWin’s global blur setting, open System Settings and go to “Apps & Windows” > “Window Management” > “Desktop Effects” and select the “Blur” plugin. If disabled, enable it by ticking the checkbox to the left. Then click on the “Configure” button and there will be two sliders that allow you to set background blur and noise intensities for all apps, including Ghostty.

All other Linux desktop environments are as of now unsupported. Users may need to set environment-specific settings and/or install third-party plugins in order to support background blur, as there isn’t a unified interface for doing so.

A value of 1 is fully opaque and a value of 0 is fully transparent. Because “0” is not useful (it makes the window look very weird), the minimum value is 0.15. This value still looks weird but you can at least see what’s going on. A value outside of the range 0.15 to 1 will be clamped to the nearest valid value.

This will default to the background color.

Specified as either hex (#RRGGBB or RRGGBB) or a named X11 color.

Available since: 1.1.0

This can be set to navigation to preserve the zoomed split state when navigating to another split (e.g. via goto_split). This will change the zoomed split to the newly focused split instead of unzooming.

Any options can also be prefixed with no- to disable that option.

Example: split-preserve-zoom = navigation

Available since: 1.3.0

Valid values:

• Hex (#RRGGBB or RRGGBB)
• Named X11 color
• “cell-foreground” to match the cell foreground color
• “cell-background” to match the cell background color

The default value is black text on a golden yellow background.

Valid values:

• Hex (#RRGGBB or RRGGBB)
• Named X11 color
• “cell-foreground” to match the cell foreground color
• “cell-background” to match the cell background color

The default value is black text on a soft peach background.

• SHELL environment variable
• passwd entry (user information)

This can contain additional arguments to run the command with. If additional arguments are provided, the command will be executed using /bin/sh -c to offload shell argument expansion.

To avoid shell expansion altogether, prefix the command with direct:, e.g. direct:nvim foo. This will avoid the roundtrip to /bin/sh but will also not support any shell parsing such as arguments with spaces, filepaths with ~, globs, etc. (Available since: 1.2.0)

You can also explicitly prefix the command with shell: to always wrap the command in a shell. This can be used to ensure our heuristics to choose the right mode are not used in case they are wrong. (Available since: 1.2.0)

This command will be used for all new terminal surfaces, i.e. new windows, tabs, etc. If you want to run a command only for the first terminal surface created when Ghostty starts, use the initial-command configuration.

Ghostty supports the common -e flag for executing a command with arguments. For example, ghostty -e fish --with --custom --args. This flag sets the initial-command configuration, see that for more information.

After the first terminal surface is created (or closed), there is no way to run this initial command again automatically. As such, setting this at runtime works but will only affect the next terminal surface if it is the first one ever created.

If you’re using the ghostty CLI there is also a shortcut to set this with arguments directly: you can use the -e flag. For example: ghostty -e fish --with --custom --args. The -e flag automatically forces some other behaviors as well:

• Disables shell expansion since the input is expected to already be shell-expanded by the upstream (e.g. the shell used to type in the ghostty -e command).
• gtk-single-instance=false - This ensures that a new instance is launched and the CLI args are respected.
• quit-after-last-window-closed=true - This ensures that the Ghostty process will exit when the command exits. Additionally, the quit-after-last-window-closed-delay is unset.
• shell-integration=detect (if not none) - This prevents forcibly injecting any configured shell integration into the command’s environment. With -e its highly unlikely that you’re executing a shell and forced shell integration is likely to cause problems (e.g. by wrapping your command in a shell, setting env vars, etc.). This is a safety measure to prevent unexpected behavior. If you want shell integration with a -e-executed command, you must either name your binary appropriately or source the shell integration script manually.

• never - Never send notifications (the default).
• unfocused - Only send notifications if the surface that the command is running in is not focused.
• always - Always send notifications.

Command finished notifications requires that either shell integration is enabled, or that your shell sends OSC 133 escape sequences to mark the start and end of commands.

On GTK, there is a context menu item that will enable command finished notifications for a single command, overriding the never and unfocused options.

Available since 1.3.0.

Available options:

• bell - enabled by default
• notify - disabled by default

Options can be combined by listing them as a comma separated list. Options can be negated by prefixing them with no-. For example no-bell,notify.

Available since 1.3.0.

The duration is specified as a series of numbers followed by time units. Whitespace is allowed between numbers and units. Each number and unit will be added together to form the total duration.

The allowed time units are as follows:

• y - 365 SI days, or 8760 hours, or 31536000 seconds. No adjustments are made for leap years or leap seconds.
• d - one SI day, or 86400 seconds.
• h - one hour, or 3600 seconds.
• m - one minute, or 60 seconds.
• s - one second.
• ms - one millisecond, or 0.001 second.
• us or µs - one microsecond, or 0.000001 second.
• ns - one nanosecond, or 0.000000001 second. Examples:
• 1h30m
• 45s

Units can be repeated and will be added together. This means that 1h1h is equivalent to 2h. This is confusing and should be avoided. A future update may disallow this.

The maximum value is 584y 49w 23h 34m 33s 709ms 551µs 615ns. Any value larger than this will be clamped to the maximum value.

Available since 1.3.0

env = foo=bar env = bar=baz

Setting env to an empty string will reset the entire map to default (empty).

env =

Setting a key to an empty string will remove that particular key and corresponding value from the map.

env = foo=bar env = foo=

will result in foo not being passed to the launched commands.

Setting a key multiple times will overwrite previous entries.

env = foo=bar env = foo=baz

will result in foo=baz being passed to the launched commands.

These environment variables will override any existing environment variables set by Ghostty. For example, if you set GHOSTTY_RESOURCES_DIR then the value you set here will override the value Ghostty typically automatically injects.

These environment variables will not be passed to commands run by Ghostty for other purposes, like open or xdg-open used to open URLs in your browser.

Available since: 1.2.0

The configured command will be launched using the typical rules, then the data specified as this input will be written to the pty before any other input can be provided.

The bytes are sent as-is with no additional encoding. Therefore, be cautious about input that can contain control characters, because this can be used to execute programs in a shell.

The format of this value is:

• raw:<string> - Send raw text as-is. This uses Zig string literal syntax so you can specify control characters and other standard escapes.
• path:<path> - Read a filepath and send the contents. The path must be to a file with finite length. e.g. don’t use a device such as /dev/stdin or /dev/urandom as these will block terminal startup indefinitely. Files are limited to 10MB in size to prevent excessive memory usage. If you have files larger than this you should write a script to read the file and send it to the terminal.

If no valid prefix is found, it is assumed to be a raw: input. This is an ergonomic choice to allow you to simply write input = "Hello, world!" (a common case) without needing to prefix every value with raw:.

This can be repeated multiple times to send more data. The data is concatenated directly with no separator characters in between (e.g. no newline).

If any of the input sources do not exist, then none of the input will be sent. Input sources are not verified until the terminal is starting, so missing paths will not show up in config validation.

Changing this configuration at runtime will only affect new terminals.

Available since: 1.2.0

This is primarily useful for scripts or debugging.

On Linux, this must be paired with a non-zero exit code. On macOS, we allow any exit code because of the way shell processes are launched via the login command.

When this limit is reached, the oldest lines are removed from the scrollback.

Scrollback currently exists completely in memory. This means that the larger this value, the larger potential memory usage. Scrollback is allocated lazily up to this limit, so if you set this to a very large value, it will not immediately consume a lot of memory.

This size is per terminal surface, not for the entire application.

It is not currently possible to set an unlimited scrollback buffer. This is a future planned feature.

This can be changed at runtime but will only affect new terminal surfaces.

The default value is system.

Valid values:

• system - Respect the system settings for when to show scrollbars. For example, on macOS, this will respect the “Scrollbar behavior” system setting which by default usually only shows scrollbars while actively scrolling or hovering the gutter.
• never - Never show a scrollbar. You can still scroll using the mouse, keybind actions, etc. but you will not have a visual UI widget showing a scrollbar.

Links that are configured earlier take precedence over links that are configured later.

A default link that matches a URL and opens it in the system opener always exists. This can be disabled using link-url.

TODO: This can’t currently be set!

The URL matcher is always lowest priority of any configured links (see link). If you want to customize URL matching, use link and disable this.

When true, link previews are shown for all matched URLs. When false, link previews are never shown. When set to “osc8”, link previews are only shown for hyperlinks created with the OSC 8 sequence (in this case, the link text can differ from the link destination).

Available since: 1.2.0

Available since: 1.1.0

Allowable values are:

• false - Don’t start in fullscreen (default)
• true - Start in native fullscreen
• non-native - (macOS only) Start in non-native fullscreen, hiding the menu bar. This is faster than native fullscreen since it doesn’t use animations. On non-macOS platforms, this behaves the same as true.
• non-native-visible-menu - (macOS only) Start in non-native fullscreen, keeping the menu bar visible. On non-macOS platforms, behaves like true.
• non-native-padded-notch - (macOS only) Start in non-native fullscreen, hiding the menu bar but padding for the notch on applicable devices. On non-macOS platforms, behaves like true.

Important: tabs DO NOT WORK with non-native fullscreen modes. Non-native fullscreen removes the titlebar and macOS native tabs require the titlebar. If you use tabs, use true (native) instead.

On macOS, true (native fullscreen) does not work if window-decoration is set to false, because native fullscreen on macOS requires window decorations.

If you want a blank title, set this to one or more spaces by quoting the value. For example, title = " ". This effectively hides the title. This is necessary because setting a blank value resets the title to the default value of the running program.

This configuration can be reloaded at runtime. If it is set, the title will update for all windows. If it is unset, the next title change escape sequence will be honored but previous changes will not retroactively be set. This latter case may require you to restart programs such as Neovim to get the new title.

This controls the class field of the WM_CLASS X11 property (when running under X11), the Wayland application ID (when running under Wayland), and the bus name that Ghostty uses to connect to DBus.

Note that changing this value between invocations will create new, separate instances, of Ghostty when running with gtk-single-instance=true. See that option for more details.

Changing this value may break launching Ghostty from .desktop files, via DBus activation, or systemd user services as the system is expecting Ghostty to connect to DBus using the default class when it is launched.

The class name must follow the requirements defined in the GTK documentation.

The default is com.mitchellh.ghostty.

This only affects GTK builds.

The default is ghostty.

This only affects GTK builds.

This setting is secondary to the window-inherit-working-directory setting. If a previous Ghostty terminal exists in the same process, window-inherit-working-directory will take precedence. Otherwise, this setting will be used. Typically, this setting is used only for the first window.

The default is inherit except in special scenarios listed next. On macOS, if Ghostty can detect it is launched from launchd (double-clicked) or open, then it defaults to home. On Linux with GTK, if Ghostty can detect it was launched from a desktop launcher, then it defaults to home.

The value of this must be an absolute path, a path prefixed with ~/ (the tilde will be expanded to the user’s home directory), or one of the special values below:

• home - The home directory of the executing user.
• inherit - The working directory of the launching process.

Trigger: +-separated list of keys and modifiers. Example: ctrl+a, ctrl+shift+b, up.

If the key is a single Unicode codepoint, the trigger will match any presses that produce that codepoint. These are impacted by keyboard layouts. For example, a will match the a key on a QWERTY keyboard, but will match the q key on a AZERTY keyboard (assuming US physical layout).

For Unicode codepoints, matching is done by comparing the set of modifiers with the unmodified codepoint. The unmodified codepoint is sometimes called an “unshifted character” in other software, but all modifiers are considered, not only shift. For example, ctrl+a will match a but not ctrl+shift+a (which is A on a US keyboard).

Further, codepoint matching is case-insensitive and the unmodified codepoint is always case folded for comparison. As a result, ctrl+A configured will match when ctrl+a is pressed. Note that this means some key combinations are impossible depending on keyboard layout. For example, ctrl+_ is impossible on a US keyboard because _ is shift+- and ctrl+shift+- is not equal to ctrl+_ (because the modifiers don’t match!). More details on impossible key combinations can be found at this excellent source written by Qt developers: https://doc.qt.io/qt-6/qkeysequence.html#keyboard-layout-issues

Physical key codes can be specified by using any of the key codes as specified by the W3C specification. For example, KeyA will match the physical a key on a US standard keyboard regardless of the keyboard layout. These are case-sensitive.

For aesthetic reasons, the w3c codes also support snake case. For example, key_a is equivalent to KeyA. The only exceptions are function keys, e.g. F1 is f1 (no underscore). This is a consequence of our internal code using snake case but is purposely supported and tested so it is safe to use. It allows an all-lowercase binding which I find more aesthetically pleasing.

Function keys such as insert, up, f5, etc. are also specified using the keys as specified by the previously linked W3C specification.

Physical keys always match with a higher priority than Unicode codepoints, so if you specify both a and KeyA, the physical key will always be used regardless of what order they are configured.

The special key catch_all can be used to match any key that is not otherwise bound. This can be combined with modifiers, for example ctrl+catch_all will match any key pressed with ctrl that is not otherwise bound. When looking up a binding, Ghostty first tries to match catch_all with modifiers. If no match is found and the event has modifiers, it falls back to catch_all without modifiers.

Valid modifiers are shift, ctrl (alias: control), alt (alias: opt, option), and super (alias: cmd, command). You may use the modifier or the alias. When debugging keybinds, the non-aliased modifier will always be used in output.

Note: The fn or “globe” key on keyboards are not supported as a modifier. This is a limitation of the operating systems and GUI toolkits that Ghostty uses.

Some additional notes for triggers:

• modifiers cannot repeat, ctrl+ctrl+a is invalid.
• modifiers and keys can be in any order, shift+a+ctrl is weird, but valid.
• only a single key input is allowed, ctrl+a+b is invalid.

You may also specify multiple triggers separated by > to require a sequence of triggers to activate the action. For example, ctrl+a>n=new_window will only trigger the new_window action if the user presses ctrl+a followed separately by n. In other software, this is sometimes called a leader key, a key chord, a key table, etc. There is no hardcoded limit on the number of parts in a sequence.

Warning: If you define a sequence as a CLI argument to ghostty, you probably have to quote the keybind since > is a special character in most shells. Example: ghostty –keybind=`ctrl+a>n=new_window'

A trigger sequence has some special handling:

• Ghostty will wait an indefinite amount of time for the next key in the sequence. There is no way to specify a timeout. The only way to force the output of a prefix key is to assign another keybind to specifically output that key (e.g. ctrl+a>ctrl+a=text:foo) or press an unbound key which will send both keys to the program.
• If an unbound key is pressed during a sequence and a catch_all binding exists that would ignore the input, the entire sequence is dropped and nothing happens. Otherwise, the entire sequence is encoded and sent to the running program as if no keybind existed.
• If a prefix in a sequence is previously bound, the sequence will override the previous binding. For example, if ctrl+a is bound to new_window and ctrl+a>n is bound to new_tab, pressing ctrl+a will do nothing.
• Adding to the above, if a previously bound sequence prefix is used in a new, non-sequence binding, the entire previously bound sequence will be unbound. For example, if you bind ctrl+a>n and ctrl+a>t, and then bind ctrl+a directly, both ctrl+a>n and ctrl+a>t will become unbound.
• Trigger sequences are not allowed for global: or all:-prefixed triggers. This is a limitation we could remove in the future.

Action is the action to take when the trigger is satisfied. It takes the format action or action:param. The latter form is only valid if the action requires a parameter.

• ignore - Do nothing, ignore the key input. This can be used to black hole certain inputs to have no effect.
• unbind - Remove the binding. This makes it so the previous action is removed, and the key will be sent through to the child command if it is printable. Unbind will remove any matching trigger, including physical:-prefixed triggers without specifying the prefix.
• csi:text - Send a CSI sequence. e.g. csi:A sends “cursor up”.
• esc:text - Send an escape sequence. e.g. esc:d deletes to the end of the word to the right.
• text:text - Send a string. Uses Zig string literal syntax. e.g. text:\x15 sends Ctrl-U.
• All other actions can be found in the documentation or by using the ghostty +list-actions command.

Some notes for the action:

•

The parameter is taken as-is after the :. Double quotes or other mechanisms are included and NOT parsed. If you want to send a string value that includes spaces, wrap the entire trigger/action in double quotes. Example: --keybind="up=csi:A B"

There are some additional special values that can be specified for keybind:

•

keybind=clear will clear all set keybindings. Warning: this removes ALL keybindings up to this point, including the default keybindings.

The keybind trigger can be prefixed with some special values to change the behavior of the keybind. These are:

•

all:

•

global:

•

unconsumed:

•

performable:

Keybind triggers are not unique per prefix combination. For example, ctrl+a and global:ctrl+a are not two separate keybinds. The keybind set later will overwrite the keybind set earlier. In this case, the global: keybind will be used.

Multiple prefixes can be specified. For example, global:unconsumed:ctrl+a=reload_config will make the keybind global and not consume the input to reload the config.

Note: global: is only supported on macOS and certain Linux platforms.

On macOS, this feature requires accessibility permissions to be granted to Ghostty. When a global: keybind is specified and Ghostty is launched or reloaded, Ghostty will attempt to request these permissions. If the permissions are not granted, the keybind will not work. On macOS, you can find these permissions in System Preferences -> Privacy & Security -> Accessibility.

On Linux, you need a desktop environment that implements the Global Shortcuts protocol as a part of its XDG desktop protocol implementation. Desktop environments that are known to support (or not support) global shortcuts include:

• Users using KDE Plasma (since 5.27) and GNOME (since 48) should be able to use global shortcuts with little to no configuration.
• Some manual configuration is required on Hyprland. Consult the steps outlined on the Hyprland Wiki to set up global shortcuts correctly. (Important: xdg-desktop-portal-hyprland must also be installed!)
• Notably, global shortcuts have not been implemented on wlroots-based compositors like Sway (see upstream issue).

Ghostty will not process this combination nor forward it to the child process within the terminal, but it may still be processed by the OS or other applications.

This cannot unbind bindings that were not bound by Ghostty or the user (e.g. bindings set by the OS or some other application).

The value should be the CSI sequence without the CSI header (ESC [ or \x1b[).

For example, csi:0m can be sent to reset all styles of the current text.

Uses Zig string literal syntax. This is currently not validated. If the text is invalid (i.e. contains an invalid escape sequence), the error will currently only show up in logs.

This can fix a lot of issues when a running program puts the terminal into a broken state, equivalent to running the reset command.

If you do this while in a TUI program such as vim, this may break the program. If you do this while in a shell, you may have to press enter after to get a new prompt.

For example, increase_font_size:1.5 will increase the font size by 1.5 points.

For example, decrease_font_size:1.5 will decrease the font size by 1.5 points.

For example, set_font_size:14.5 will set the font size to 14.5 points.

If a previous search is active, it is replaced.

Positive values scroll downwards, and negative values scroll upwards.

For example, scroll_page_fractional:0.5 would scroll the screen downwards by half a page, while scroll_page_fractional:-1.5 would scroll it upwards by one and a half pages.

Positive values scroll downwards, and negative values scroll upwards.

For example, scroll_page_lines:3 would scroll the screen downwards by 3 lines, while scroll_page_lines:-10 would scroll it upwards by 10 lines.

WARNING: This does not create a new selection, and does nothing when there currently isn’t one.

Valid arguments are:

•

left, right

•

up, down

•

page_up, page_down

•

home, end

•

beginning_of_line, end_of_line

Requires shell integration.

Positive values scroll downwards, and negative values scroll upwards.

Valid actions are:

•

copy

•

paste

•

open

See write_scrollback_file for possible actions.

See write_scrollback_file for possible actions.

Does nothing when no text is selected.

If the application isn’t currently focused, this will bring it to the front.

If the tab number is higher than the number of tabs, this will go to the last tab.

Positive values move the tab forwards, and negative values move it backwards. If the new position is out of bounds, it is wrapped around cyclically within the tab list.

For example, move_tab:1 moves the tab one position forwards, and if it was already the last tab in the list, it wraps around and becomes the first tab in the list. Likewise, move_tab:-1 moves the tab one position backwards, and if it was the first tab, then it will become the last tab.

This is only supported on Linux and when the system’s libadwaita version is 1.4 or newer. The current libadwaita version can be found by running ghostty +version.

If the title is empty, the surface title is reset to an empty title.

If the title is empty, the tab title override is cleared.

Valid arguments:

•

right, down, left, up

•

auto

When a split is zoomed into, it will take up the entire space in the current tab, hiding other splits. The tab or tab bar would also reflect this by displaying an icon indicating the zoomed state.

• No input is sent to the PTY (mouse events, key encoding)
• Input can still be used at the terminal level to make selections, copy/paste (keybinds), scroll, etc.
• Warn before quit is always enabled in this state even if an active process is not running

Only implemented on macOS.

Valid arguments: toggle, show, hide.

Has no effect on macOS.

Only implemented on Linux (GTK). On GNOME, the “Screen Keyboard” accessibility feature must be turned on, which can be found under Settings > Accessibility > Typing. Other platforms are as of now untested.

If your default OS editor isn’t configured then this will fail. Currently, any failures to open the configuration will show up only in the logs.

The exact meaning depends on the app runtime in use, but this usually involves re-reading the configuration file and applying any changes Note that not all changes can be applied at runtime.

This might trigger a close confirmation popup, depending on the value of the confirm-close-surface configuration setting.

If the mode is not specified, defaults to closing the current tab.

This might trigger a close confirmation popup, depending on the value of the confirm-close-surface configuration setting.

This might trigger a close confirmation popup, depending on the value of the confirm-close-surface configuration setting.

WARNING: This action has been deprecated and has no effect on either Linux or macOS. Users are instead encouraged to use all:close_window instead.

This has no effect on macOS as it does not have the concept of maximized windows.

Only implemented on Linux.

Terminal windows always start as normal (not float-on-top) windows.

Only implemented on macOS.

This is used to prevent apps from monitoring your keyboard input when entering passwords or other sensitive information.

This applies to the entire application, not just the focused terminal. You must manually untoggle it or quit Ghostty entirely to disable it.

Only implemented on macOS, as this uses a built-in system API.

When mouse reporting is disabled, mouse events will not be reported to terminal applications even if they request it. This allows you to always use the mouse for selection and other terminal UI interactions without applications capturing mouse input.

This can also be controlled via the mouse-reporting configuration option.

The command palette is a popup that lets you see what actions you can perform, their associated keybindings (if any), a search bar to filter the actions, and the ability to then execute the action.

This requires libadwaita 1.5 or newer on Linux. The current libadwaita version can be found by running ghostty +version.

The quick terminal, also known as the “Quake-style” or drop-down terminal, is a terminal window that appears on demand from a keybinding, often sliding in from a screen edge such as the top. This is useful for quick access to a terminal without having to open a new window or tab.

The terminal state is preserved between appearances, so showing the quick terminal after it was already hidden would display the same window instead of creating a new one.

As quick terminals are often useful when other windows are currently focused, they are best used with global keybinds. For example, one can define the following key bind to toggle the quick terminal from anywhere within the system by pressing Cmd+`:

keybind = global:cmd+backquote=toggle_quick_terminal
    

The quick terminal has some limitations:

• Only one quick terminal instance can exist at a time.
• Unlike normal terminal windows, the quick terminal will not be restored when the application is restarted on systems that support window restoration like macOS.
• On Linux, the quick terminal is only supported on Wayland and not X11, and only on Wayland compositors that support the wlr-layer-shell-v1 protocol. In practice, this means that only GNOME users would not be able to use this feature.
• On Linux, slide-in animations are only supported on KDE, and when the “Sliding Popups” KWin plugin is enabled.

• Quick terminal tabs are only supported on Linux and not on macOS. This is because tabs on macOS require a title bar.
• On macOS, a fullscreened quick terminal will always be in non-native fullscreen mode. This is a requirement due to how the quick terminal is rendered.

See the various configurations for the quick terminal in the configuration file to customize its behavior.

Note: When the focused surface is fullscreen, this method does nothing.

Only implemented on macOS.

This does nothing when background-opacity is set to 1 or above.

When background-opacity is less than 1, this action will either make the window transparent or not depending on its current transparency state.

Only implemented on macOS.

Only implemented on macOS.

Not every action in Ghostty can be undone or redone. The list of actions support undo/redo is currently limited to:

• New window, close window
• New tab, close tab
• New split, close split

All actions are only undoable/redoable for a limited time. For example, restoring a closed split can only be done for some number of seconds since the split was closed. The exact amount is configured with the undo-timeout configuration settings.

The undo/redo actions being limited ensures that there is bounded memory usage over time, closed surfaces don’t continue running in the background indefinitely, and the keybinds become available for terminal applications to use.

Only implemented on macOS.

For example: ctrl+w>escape=end_key_sequence would encode ctrl+w to the terminal and exit the key sequence.

Normally, an invalid sequence will reset the key sequence and flush all data including the invalid key. This action allows you to flush only the prior keys, which is useful when you want to bind something like a control key (ctrl+w) but not send additional inputs.

If the named key table does not exist, this action has no effect and performable will report false.

If the named key table is already the currently active key table, this action has no effect and performable will report false.

The “once” check is only done if this is the currently active key table. If another key table is activated later, then this table will remain active until it pops back out to being the active key table.

WARNING: This is a hard crash (panic) and data can be lost.

The purpose of this action is to test crash handling. For some users, it may be useful to test crash reporting functionality in order to determine if it all works as expected.

The value determines the crash location:

•

main

•

io

•

render