Ghostty Terminal Configuration
Info
This guide provides a quickstart using ghostty — from the config file itself, to theming, transparency, and window sizing.
Master quick append
Paste into ~/.config/ghostty/config.ghostty, then reload with Ctrl+Shift+,. Each option is explained in the sections below.
# transparency: lower is more transparent (blur needs Blur my Shell on GNOME)
background-opacity = 0.8
background-blur = true
# initial window grid size in columns and rows
window-width = 120
window-height = 40
# restore window state across launches: default | never | always
window-save-state = never
# ask before closing a tab, split, or window: true | false | always
confirm-close-surface = alwaysOn GNOME, Ctrl+Alt+Up/Down conflicts with ghostty's split-focus shortcuts — see Focus-Split Up/Down on GNOME below to fix it.
Installation
For the official install guide from Ghostty, see the upstream documentation.
Note that ghostty has no single official Linux package except for Arch — the methods below are the recommended community approaches.
Ubuntu users can use the community install script:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/mkasberg/ghostty-ubuntu/HEAD/install.sh)"Warning
This is an Ubuntu-focused installer and may not be compatible with Debian. Before running any curl | bash script, we recommend inspecting it first at mkasberg/ghostty-ubuntu. For anything outside Ubuntu, refer to the official install guide.
ghostty is in the official [extra] repository:
sudo pacman -S ghosttyPrerelease builds are available in the AUR as ghostty-git.
Config File
Location and syntax
ghostty reads its configuration from ~/.config/ghostty/config.ghostty.
The file uses a simple key = value format
- One key per line.
- Keys are case-sensitive.
- Comments must be on their own line starting with
#; inline trailing comments are not supported. - Setting a key to an empty value (e.g.
theme =) resets it to its default.
# This is a valid comment
theme = Everforest Dark Hard
background-opacity = 0.8Reloading the config
Ctrl+Shift+, (the default keybind on Linux) to reload it at runtime.
Theme and Transparency
Applying a theme
Tips
Run ghostty +list-themes in a terminal to browse all built-in themes before committing to one.
theme = Everforest Dark HardBackground transparency and blur
# background-opicity: lower is more transparent
background-opacity = 0.8
background-blur = trueWarning
background-blur relies on the KDE blur protocol; on a standard GNOME Wayland session, background-blur is ignored. Transparency (background-opacity) still works — only blur is N/A.
If you want blur on GNOME, install the Blur my Shell extension and enable its application blur to blur for ghostty.
Default Window Size
The keys window-width and window-height set the initial terminal grid size in rows and columns.
The default 0 lets the OS or window manager decide. Both keys must be set together for the config to be valid.
window-width = 120
window-height = 40window-save-state controls whether ghostty restores the previous window state (including size) across launches. Accepted values are default, never, and always.
window-save-state = neverClose Confirmation
confirm-close-surface decides whether ghostty asks before closing a tab, split, or window.
true(default) asks only when a program is still running, such asvimor an update.falsenever asks.alwaysasks every time, even at an empty prompt. This guards against a strayCtrl+Shift+Wor a misclick on the close button.
confirm-close-surface = alwaysKeyboard Shortcuts
ghostty ships with sensible default keybinds. For reference, see this keyboard shortcuts cheatsheet.
Focus-Split Up/Down on GNOME
Ctrl+Alt+Up and Ctrl+Alt+Down are grabbed by the GNOME compositor for vertical workspace switching. This means the default focus-split up/down shortcuts do not fire. The left/right directions (Ctrl+Alt+Left / Ctrl+Alt+Right) are unaffected.
Quick fix
gsettings set org.gnome.desktop.wm.keybindings switch-to-workspace-up "[]"
gsettings set org.gnome.desktop.wm.keybindings switch-to-workspace-down "[]"GNOME Keyboard Shortcut
We can bind a key combo in GNOME Settings to launch ghostty to access the terminal quickly.
Open keyboard shortcuts
Open
Settings->Keyboard. Under "Keyboard Shortcuts", clickView and Customise Shortcuts.Navigate to custom shortcuts
Scroll to the bottom of the list and select
Custom Shortcuts, then click the+button to add a new entry.Fill in the shortcut details
Enter a name (e.g. "Ghostty") and set the command to
ghostty.Set the key combo
Click
Set Shortcutand press your desired combination — for exampleSuper+ReturnorCtrl+Alt+T.Confirm
Click
Addto save. The shortcut is active immediately — no logout required.
Contributors
Changelog
b96a3-on3c19f-onc1fd3-ondfe76-on7150e-on47a19-on87203-on5ba10-ond1c34-one8637-onf30ac-onb2019-on