>

Restart a User LaunchAgent with bootout and bootstrap

Unload and reload a stuck or misbehaving user agent through launchd instead of killing its process.

macOSlaunchctlservicestroubleshootingMedium risk
Run launchctl bootout gui/$UID/<label>, then launchctl bootstrap gui/$UID ~/Library/LaunchAgents/<label>.plist to stop the agent and start it fresh from its plist.

01Command

Command
$ launchctl bootout gui/$UID/<label> && launchctl bootstrap gui/$UID ~/Library/LaunchAgents/<label>.plist

02What it does

bootout removes a service from your user's gui domain, which stops its process and drops launchd's in-memory state for it; bootstrap re-reads the plist on disk and starts the service as if you had just logged in. The legacy equivalents are launchctl unload and launchctl load, which Apple now marks as legacy and which still work on current macOS versions.

03Risk

RiskMedium risk
!Warning: bootout fails with an error if the agent is not currently loaded — that is expected and the bootstrap can still run. If the service is managed by brew services, restart it with brew instead so brew's records stay in sync.

04Undo

Undo
$ launchctl bootout gui/$UID/<label>

05Sources

  • launchctl — interact with launchd (macOS)
    SS64 · technical · 2026-09-17
    Evidence: The page documents bootout domain/service-target as "Remove domain/service (equivalent to unload in the legacy syntax)", shows the gui/uid/[service-name] specifier form, and gives examples pairing bootout with the new syntax against legacy unload.
  • launchctl(1) — macOS man page
    KEITH · technical · 2026-09-17
    Evidence: The man page documents bootstrap gui/uid <plist-path> to load a service into the user's gui domain and bootout gui/uid/service-label to remove it, noting these replace the legacy load/unload subcommands.

Last verified: 2026-09-19 · Category: System & Settings

06Related solutions

Inspect and Restart Services with launchctl print
macOSdaemonslaunchctllaunchd

The modern launchctl interface — full state of any launchd job plus a restart that actually works.

Medium risk ✓ 2026-09-17
Search the Unified Log with log show
macOSlogtroubleshootinglogging

Filter macOS's single unified log by process, message type, or subsystem straight from the Terminal.

Low risk ✓ 2026-09-17
Trace Real-Time Filesystem Activity with fs_usage
macOSfs_usagefilesystemdtrace

Watch every open, write, and stat call happening on your disks and see exactly which process made it.

Medium risk ✓ 2026-09-17