Back to Details

ghostty-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ghostty Configuration

Ghostty 配置

Guidance for configuring the Ghostty terminal emulator. Ghostty uses text-based config files with sensible defaults and zero required configuration.
Ghostty终端模拟器配置指南。Ghostty采用基于文本的配置文件，拥有合理的默认设置，且无需强制配置。

Config File Locations

配置文件位置

XDG Path (All Platforms):
  • $XDG_CONFIG_HOME/ghostty/config
  • Defaults to 
    ~/.config/ghostty/config
    if XDG_CONFIG_HOME undefined
macOS Additional Path:
  • ~/Library/Application Support/com.mitchellh.ghostty/config
  • If both XDG and macOS paths exist, both are loaded with macOS path taking precedence
XDG路径（全平台）：
  • $XDG_CONFIG_HOME/ghostty/config
  • 如果未定义XDG_CONFIG_HOME，则默认路径为
    ~/.config/ghostty/config
macOS额外路径：
  • ~/Library/Application Support/com.mitchellh.ghostty/config
  • 若XDG路径和macOS路径同时存在，两者都会被加载，且macOS路径优先级更高

Config Syntax

配置语法

undefined
undefined

Comments start with

注释以#开头

background = 282c34 foreground = ffffff font-family = "JetBrains Mono" keybind = ctrl+z=close_surface font-family = # Empty value resets to default

**Rules:**
- Keys are **case-sensitive** (use lowercase)
- Whitespace around `=` is flexible
- Values can be quoted or unquoted
- Empty values reset to defaults
- Every config key works as CLI flag: `ghostty --background=282c34`
background = 282c34 foreground = ffffff font-family = "JetBrains Mono" keybind = ctrl+z=close_surface font-family = # 空值会重置为默认值

**规则：**
- 键名区分大小写（请使用小写）
- `=`两侧的空格可灵活调整
- 值可以加引号或不加引号
- 空值会重置为默认设置
- 所有配置键均可作为CLI标志使用：`ghostty --background=282c34`

Config Loading & Includes

配置加载与引入

Files processed sequentially - later entries override earlier ones.
undefined
配置文件按顺序处理 - 后续条目会覆盖之前的条目。
undefined

Include additional configs

引入额外配置文件

config-file = themes/dark.conf config-file = ?local.conf # ? prefix = optional (no error if missing)

**Critical:** `config-file` directives are processed at the file's end. Keys appearing after `config-file` won't override the included file's values.
config-file = themes/dark.conf config-file = ?local.conf # ?前缀表示可选（文件不存在时不会报错）

**重要提示：**`config-file`指令会在文件末尾处理。出现在`config-file`之后的配置键不会覆盖引入文件中的值。

Runtime Reloading

运行时重载

  • Linux: 
    ctrl+shift+,
  • macOS: 
    cmd+shift+,
Some options cannot be reloaded at runtime. Some apply only to newly created terminals.
  • Linux： 
    ctrl+shift+,
  • macOS： 
    cmd+shift+,
部分选项无法在运行时重载，部分选项仅对新创建的终端生效。

CLI Commands

CLI命令

Ghostty provides CLI actions via 
ghostty +<action>
. Use 
ghostty +<action> --help
for action-specific help.
Ghostty通过
ghostty +<action>
提供CLI操作。使用
ghostty +<action> --help
查看操作的专属帮助信息。

Configuration Commands

配置相关命令

CommandDescription
ghostty +show-config
Show current effective configuration
ghostty +show-config --default
Show default configuration
ghostty +show-config --default --docs
Show defaults with documentation
ghostty +validate-config
Validate configuration file for errors
ghostty +edit-config
Open config file in default editor
命令描述
ghostty +show-config
显示当前生效的配置
ghostty +show-config --default
显示默认配置
ghostty +show-config --default --docs
显示带文档说明的默认配置
ghostty +validate-config
验证配置文件是否存在错误
ghostty +edit-config
在默认编辑器中打开配置文件

Listing Commands

列表类命令

CommandDescription
ghostty +list-fonts
List available fonts (fixed-width)
ghostty +list-themes
List available colour themes
ghostty +list-keybinds
Show current keybindings
ghostty +list-keybinds --default
Show default keybindings
ghostty +list-colors
List available colour names
ghostty +list-actions
List all available keybinding actions
命令描述
ghostty +list-fonts
列出可用的等宽字体
ghostty +list-themes
列出可用的配色主题
ghostty +list-keybinds
显示当前的快捷键绑定
ghostty +list-keybinds --default
显示默认的快捷键绑定
ghostty +list-colors
列出可用的颜色名称
ghostty +list-actions
列出所有可用的快捷键绑定操作

Other Commands

其他命令

CommandDescription
ghostty +version
Show version information
ghostty +help
Show help
ghostty +show-face
Show font face information
ghostty +ssh-cache
Manage SSH terminfo cache
ghostty +crash-report
Generate crash report
ghostty +new-window
Open new window (Linux only)
ghostty +boo
Easter egg
命令描述
ghostty +version
显示版本信息
ghostty +help
显示帮助信息
ghostty +show-face
显示字体外观信息
ghostty +ssh-cache
管理SSH terminfo缓存
ghostty +crash-report
生成崩溃报告
ghostty +new-window
打开新窗口（仅Linux支持）
ghostty +boo
复活节彩蛋

Launching with Options

带选项启动

Every config key works as a CLI flag:
bash
ghostty --background=282c34 --font-size=14
ghostty -e top                              # Run command in terminal
macOS Note: The 
ghostty
CLI is a helper tool. To launch the terminal use 
open -na Ghostty.app
or 
open -na Ghostty.app --args --font-size=14
.
所有配置键均可作为CLI标志使用：
bash
ghostty --background=282c34 --font-size=14
ghostty -e top                              # 在终端中运行指定命令
macOS注意事项：
ghostty
CLI是一个辅助工具。要启动终端，请使用
open -na Ghostty.app
或
open -na Ghostty.app --args --font-size=14
。

Keybinding Syntax

快捷键绑定语法

Format: 
keybind = trigger=action
格式：
keybind = 触发键=操作

Triggers

触发键

Modifiers: 
shift
, 
ctrl
/
control
, 
alt
/
opt
/
option
, 
super
/
cmd
/
command
keybind = ctrl+a=select_all
keybind = ctrl+shift+t=new_tab
keybind = super+backquote=toggle_quick_terminal
Physical keys (W3C codes): 
KeyA
, 
key_a
, 
Digit1
, 
BracketLeft
  • Physical keys have higher priority than unicode codepoints
  • Use for non-US keyboard layouts
Key sequences (leader keys):
keybind = ctrl+a>n=new_window      # Press ctrl+a, release, press n
keybind = ctrl+a>ctrl+n=new_window # Both with ctrl
Sequences wait indefinitely for next key.
修饰键：
shift
, 
ctrl
/
control
, 
alt
/
opt
/
option
, 
super
/
cmd
/
command
keybind = ctrl+a=select_all
keybind = ctrl+shift+t=new_tab
keybind = super+backquote=toggle_quick_terminal
物理键（W3C编码）：
KeyA
, 
key_a
, 
Digit1
, 
BracketLeft
  • 物理键的优先级高于Unicode码点
  • 适用于非美式键盘布局
按键序列（引导键）：
keybind = ctrl+a>n=new_window      # 先按ctrl+a，松开后按n
keybind = ctrl+a>ctrl+n=new_window # 两次都按住ctrl
序列会无限等待下一个按键输入。

Prefixes

前缀

PrefixEffect
global:
System-wide (macOS: needs Accessibility permissions; Linux: needs XDG Desktop Portal)
all:
Apply to all terminal surfaces
unconsumed:
Don't consume input (passes through)
performable:
Only consume if action succeeds
Combine prefixes: 
global:unconsumed:ctrl+a=reload_config
Note: Sequences cannot be used with 
global:
or 
all:
prefixes.
前缀效果
global:
系统全局生效（macOS：需要辅助功能权限；Linux：需要XDG Desktop Portal）
all:
应用于所有终端界面
unconsumed:
不消耗输入（会传递给下层）
performable:
仅在操作成功时才消耗输入
可组合前缀：
global:unconsumed:ctrl+a=reload_config
**注意：**按键序列无法与
global:
或
all:
前缀一起使用。

Special Values

特殊值

  • keybind = clear
    - Remove ALL keybindings
  • keybind = ctrl+a=unbind
    - Remove specific binding
  • keybind = ctrl+a=ignore
    - Prevent processing by Ghostty and terminal
  • keybind = clear
    - 移除所有快捷键绑定
  • keybind = ctrl+a=unbind
    - 移除指定的快捷键绑定
  • keybind = ctrl+a=ignore
    - 阻止Ghostty和终端处理该按键

Shell Integration

Shell集成

Auto-injection for: bash, zsh, fish, elvish
shell-integration = detect    # Default - auto-detect shell
shell-integration = none      # Disable auto-injection
shell-integration = fish      # Force specific shell
自动注入支持：bash, zsh, fish, elvish
shell-integration = detect    # 默认值 - 自动检测Shell类型
shell-integration = none      # 禁用自动注入
shell-integration = fish      # 强制指定Shell类型

Shell Integration Features

Shell集成功能

shell-integration-features = cursor,sudo,title
shell-integration-features = no-cursor    # Disable specific feature
FeatureDescription
cursor
Blinking bar at prompt
sudo
Preserve terminfo with sudo
title
Set window title from shell
ssh-env
SSH environment compatibility
ssh-terminfo
Auto terminfo on remote hosts
shell-integration-features = cursor,sudo,title
shell-integration-features = no-cursor    # 禁用特定功能
功能描述
cursor
在提示符处显示闪烁光标
sudo
使用sudo时保留terminfo信息
title
根据Shell设置窗口标题
ssh-env
SSH环境兼容性
ssh-terminfo
在远程主机上自动配置terminfo

What Shell Integration Enables

Shell集成带来的功能

  1. Smart close (no confirm when at prompt)
  2. New terminals start in previous terminal's directory
  3. Prompt resizing via redraw
  4. Ctrl/Cmd+triple-click selects command output
  5. jump_to_prompt
    keybinding works
  6. Alt/Option+click repositions cursor at prompt
  1. 智能关闭（在提示符位置时无需确认）
  2. 新终端会在之前终端的目录中启动
  3. 通过重绘调整提示符大小
  4. Ctrl/Cmd+三击选中命令输出
  5. jump_to_prompt
    快捷键绑定生效
  6. Alt/Option+点击可将光标定位到提示符处

Manual Setup (if auto-injection fails)

手动配置（自动注入失败时）

Bash (add to 
~/.bashrc
at top):
bash
if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
    builtin source "${GHOSTTY_RESOURCES_DIR}/shell-integration/bash/ghostty.bash"
fi
Zsh:
zsh
source ${GHOSTTY_RESOURCES_DIR}/shell-integration/zsh/ghostty-integration
Fish:
fish
source "$GHOSTTY_RESOURCES_DIR"/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish
macOS Note: 
/bin/bash
does NOT support automatic shell integration. Install Bash via Homebrew or manually source the script.
Bash（添加到
~/.bashrc
顶部）：
bash
if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
    builtin source "${GHOSTTY_RESOURCES_DIR}/shell-integration/bash/ghostty.bash"
fi
Zsh：
zsh
source ${GHOSTTY_RESOURCES_DIR}/shell-integration/zsh/ghostty-integration
Fish：
fish
source "$GHOSTTY_RESOURCES_DIR"/shell-integration/fish/vendor_conf.d/ghostty-shell-integration.fish
macOS注意事项：
/bin/bash
不支持自动Shell集成。请通过Homebrew安装Bash，或手动引入脚本。

Common Configuration Patterns

常见配置模式

Theme with Light/Dark Mode

明暗主题切换

theme = light:catppuccin-latte,dark:catppuccin-mocha
theme = light:catppuccin-latte,dark:catppuccin-mocha

Quick Terminal (Drop-down)

快速终端（下拉式）

quick-terminal-position = top
quick-terminal-size = 50%
quick-terminal-autohide = true
keybind = global:super+backquote=toggle_quick_terminal
quick-terminal-position = top
quick-terminal-size = 50%
quick-terminal-autohide = true
keybind = global:super+backquote=toggle_quick_terminal

Custom Colour Palette

自定义配色方案

palette = 0=#1d2021
palette = 1=#cc241d
palette = 0=#1d2021
palette = 1=#cc241d

... (0-255 supported)

...（支持0-255号颜色）

undefined
undefined

Font Configuration

字体配置

font-family = "JetBrains Mono"
font-family-bold = "JetBrains Mono Bold"
font-size = 14
font-feature = -calt        # Disable ligatures
font-feature = -liga
font-family = "JetBrains Mono"
font-family-bold = "JetBrains Mono Bold"
font-size = 14
font-feature = -calt        # 禁用连字
font-feature = -liga

Background Transparency

背景透明度

background-opacity = 0.9
background-blur = true      # macOS, KDE Plasma only
background-opacity = 0.9
background-blur = true      # 仅支持macOS、KDE Plasma

Platform-Specific Notes

平台专属说明

macOS Only:
  • window-position-x/y
    , 
    window-save-state
    , 
    window-step-resize
  • window-vsync
    , 
    window-colorspace
  • macos-titlebar-style
    , 
    toggle_window_float_on_top
  • font-thicken
    , 
    font-thicken-strength
  • toggle_visibility
    , 
    undo
    , 
    redo
    , 
    check_for_updates
  • Global keybindings require Accessibility permissions
Linux/GTK Only:
  • window-title-font-family
    , 
    window-subtitle
  • window-titlebar-background/foreground
    (requires 
    window-theme = ghostty
    )
  • window-show-tab-bar
    , 
    gtk-single-instance
  • toggle_maximize
    , 
    toggle_window_decorations
  • toggle_tab_overview
    , 
    toggle_command_palette
  • prompt_surface_title
Linux Wayland Only:
  • quick-terminal-keyboard-interactivity
  • gtk-quick-terminal-layer
    , 
    gtk-quick-terminal-namespace
FreeType (Linux) Only:
  • freetype-load-flags
仅macOS支持：
  • window-position-x/y
    , 
    window-save-state
    , 
    window-step-resize
  • window-vsync
    , 
    window-colorspace
  • macos-titlebar-style
    , 
    toggle_window_float_on_top
  • font-thicken
    , 
    font-thicken-strength
  • toggle_visibility
    , 
    undo
    , 
    redo
    , 
    check_for_updates
  • 全局快捷键绑定需要辅助功能权限
仅Linux/GTK支持：
  • window-title-font-family
    , 
    window-subtitle
  • window-titlebar-background/foreground
    （需要设置
    window-theme = ghostty
    ）
  • window-show-tab-bar
    , 
    gtk-single-instance
  • toggle_maximize
    , 
    toggle_window_decorations
  • toggle_tab_overview
    , 
    toggle_command_palette
  • prompt_surface_title
仅Linux Wayland支持：
  • quick-terminal-keyboard-interactivity
  • gtk-quick-terminal-layer
    , 
    gtk-quick-terminal-namespace
仅FreeType（Linux）支持：
  • freetype-load-flags

Reference Files

参考文件

For complete option and keybinding references, load:
  • references/options.md
     - All config options by category (font, colour, window, etc.)
  • references/keybindings.md
     - All keybinding actions with parameters
Load these when you need specific option details, valid values, or keybinding action syntax.
如需完整的选项和快捷键绑定参考，请查看：
  • references/options.md
     - 按类别划分的所有配置选项（字体、颜色、窗口等）
  • references/keybindings.md
     - 所有带参数的快捷键绑定操作
当你需要了解特定选项的详细信息、有效值或快捷键绑定操作语法时，请查阅这些文件。