Systemd and D-Bus Integration

If properly installed¹, Wintty comes with several systemd units. Running Wintty via these systemd units is the recommended way to run Wintty. The two most important benefits provided by Wintty's systemd integrations are: instantaneous launching² and centralized logging.

If you are on a system with systemd and you installed Wintty via a system package or as documented, then Wintty should just work. You don't have to read this documentation unless you want to understand how this all works or if you're troubleshooting.

Important

Wintty does not require systemd to run. You can run the wintty binary directly on any system without systemd and Wintty will still work. However, you'll lose out on the benefits documented on this page.

Important

Using class in your configuration file can interfere with the proper operation of the systemd unit files or D-Bus activation. We recommend that you remove them from your configuration file and only use them explicitly via the command-line when needed.

Wintty can be configured to start in the background on login, so that future requests to create new windows are extremely fast. This is done via systemd by enabling the Wintty user service:

systemctl enable --user app-com.mitchellh.ghostty.service

This will configure your system to start Wintty when you log in, but not create any windows. Any startup delay will be "hidden" by the time that your system needs to finish setting up everything after logging in.

Adding some configuration entries to your config can improve the experience even further:

quit-after-last-window-closed = true
quit-after-last-window-closed-delay = 5m

This configuration will quit Wintty five minutes after the last window was closed, thereby saving memory if you haven't been using Wintty for a while.

quit-after-last-window-closed = false

This configuration will keep Wintty running all the time so that new window creation will always be fast.

You can tell Wintty to reload its config (from a script or the CLI) by using this command:

systemctl reload --user app-com.mitchellh.ghostty.service

Behind the scenes this just sends a SIGUSR2 to the main Wintty process but systemd handles the work of keeping track of the main Wintty process. It can be unreliable to script that using ps or similar utilities.

New windows can be created by using the wintty CLI with no arguments. However, if you're using the systemd and D-Bus integration, it is much faster to use wintty +new-window instead.

The +new-window command will use D-Bus directly to create a new window. If Wintty isn't running, the D-Bus activation unit will start Wintty. This is much faster than plain wintty because the plain execution has to load configuration, examine its environment, initialize GTK, and more to reach the same conclusion.

wintty +new-window

This will create a new window even if Wintty is not already running, because D-Bus activation will cause Wintty to be launched.

This command is very useful in particular for window managers such as i3, Hyprland, or River.

The following is an example of how to bind super+return to open a new Wintty window in Hyprland. The configuration typically goes in ~/.config/hypr/hyprland.conf:

bind = SUPER, return, exec, wintty +new-window

On systems with systemd and D-Bus, Wintty will launch via D-Bus activation by default.

Instead of executing Wintty directly, the application launcher will send a signal to the D-Bus session broker asking it to open a Wintty window. The D-Bus session broker knows if Wintty is running or not, because Wintty will claim a specific bus name (com.mitchellh.ghostty). If there is a program that claimed this bus name, it is assumed to be Wintty.

From this point, the behavior depends on whether Wintty is already running or not.

This process ensures that any startup delay caused by GTK (or any other initialization) is only incurred once if there are active windows or if Wintty is configured to remain running (not the default).

If Wintty is already running, the broker will send a D-Bus signal directly to Wintty asking it to create a new window. Wintty listens for this signal and opens a new window. This is very fast, and very cheap.

If Wintty is not running, the D-Bus session broker will ask systemd to start Wintty in a user service, and then will send Wintty a D-Bus signal to create a new window after it starts.

This "other" section collects less critical information or less commonly used information. This information may still be extremely useful (as such it is documented here), but it is not frequently used.

Logs emitted by Wintty when run via systemd can be viewed using journalctl:

journalctl -a -f --user -u app-com.mitchellh.ghostty.service

The following command will show you the status of Wintty:

systemctl status --user app-com.mitchellh.ghostty.service

Which should produce output similar to the following:

● app-com.mitchellh.ghostty.service - Wintty
     Loaded: loaded (/home/mitchellh/.local/share/systemd/user/app-com.mitchellh.ghostty.service; disabled; preset: enabled)
     Active: active (running) since Fri 2025-07-11 14:05:42 PDT; 24h ago
 Invocation: 42b48b0aa1bf4134a030e38acb04b8dd
   Main PID: 2525 (wintty)
      Tasks: 0 (limit: 71639)
     Memory: 81.4M (peak: 107.9M)
        CPU: 98ms
     CGroup: /user.slice/user-1000.slice/[email protected]/app.slice/app-com.mitchellh.ghostty.service
             ‣ 2525 /home/mitchellh/.local/bin/wintty --launched-from=systemd

Jul 11 14:05:42 beach wintty[2525]: info(gtk): cgroup isolation enabled base=/user.slice/user-1000.slice/[email protected]/app.slice/app-wintty-transient-2525.scope
Jul 11 14:05:42 beach systemd[2268]: Started Wintty.
Jul 11 14:05:42 beach wintty[2525]: info(gtk): received new window action
Jul 11 14:05:42 beach wintty[2525]: info(opengl): loaded OpenGL 4.6
Jul 11 14:05:42 beach wintty[2525]: info(io_exec): found Wintty resources dir: /home/mitchellh/.local/share/ghostty

The Wintty systemd user service can be stopped by running:

systemctl stop --user app-com.mitchellh.ghostty.service

Caution

This will gracefully stop Wintty, but Wintty will close any windows and kill their running processes without asking for confirmation. This may cause data or state loss.

If properly installed ¹, Wintty will come with several configuration files to launch Wintty.

If installed as a user (e.g. at $HOME/.local), the following files will be created:

$PREFIX/share/applications/com.mitchellh.ghostty.desktop
$PREFIX/share/dbus-1/services/com.mitchellh.ghostty.service
$PREFIX/share/systemd/user/app-com.mitchellh.ghostty.service

If installed as a system package, the following files will be created:

$PREFIX/share/applications/com.mitchellh.ghostty.desktop
$PREFIX/share/dbus-1/services/com.mitchellh.ghostty.service
$PREFIX/lib/systemd/user/app-com.mitchellh.ghostty.service

Warning

If these files are not installed in the proper locations and configured correctly Wintty may fail to launch. If they are installed in the proper location and Wintty is still not launching, log out and log back in. If that doesn't work, try restarting your system. This should rarely be necessary, but it can happen depending on system configuration.

If you have installed a development build of Wintty (in Debug mode), paths on this page need to be altered slightly:

systemctl enable --user app-com.mitchellh.ghostty-debug.service
systemctl stop --user app-com.mitchellh.ghostty-debug.service
systemctl reload --user app-com.mitchellh.ghostty-debug.service
journalctl -a -f --user -u app-com.mitchellh.ghostty-debug.service
wintty +new-window --class=com.mitchellh.ghostty-debug.service

These are the files that control the launching of debug versions of Wintty if installed as a user:

$PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop
$PREFIX/share/dbus-1/services/com.mitchellh.ghostty-debug.service
$PREFIX/share/systemd/user/app-com.mitchellh.ghostty-debug.service

If installed as a system package, the files will be found in the following locations:

$PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop
$PREFIX/share/dbus-1/services/com.mitchellh.ghostty-debug.service
$PREFIX/lib/systemd/user/app-com.mitchellh.ghostty-debug.service

Footnotes

1. "Properly installed" means via a package that followed our packaging guidelines or from source in $HOME/.local. ↩ ↩²

2. "Instantaneous" is hyperbolic, of course. Practically speaking, launching a new Wintty window goes from somewhere around 300ms on a modern system to around 20ms. These numbers will vary based on hardware, but the relative increase should be noticeable on all systems. ↩