# launchctl — Control Services and Daemons with launchd

> Practical guide to launchctl — load, start, stop and manage macOS daemons and agents with the modern bootstrap/bootout syntax.

Source: https://www.jpkc.com/db/en/cheatsheets/macos/launchctl/

<!-- PROSE:intro -->
launchctl is the command-line tool you use to control launchd – the central service manager of macOS that loads, starts and stops daemons and agents. Services are described by property list files (plists) living in the LaunchDaemons and LaunchAgents directories; launchctl registers them, unloads them again and shows you their status. This guide walks you through the commands you reach for most – from querying status to the modern `bootstrap`/`bootout` workflow and enabling services at startup.
<!-- PROSE:intro:end -->

## List & Info

`launchctl list` — List all loaded services for the current user.

```bash
launchctl list
```

`launchctl list | grep <name>` — Search for a specific service.

```bash
launchctl list | grep ssh
```

`launchctl print system/<label>` — Show detailed info about a system service.

```bash
sudo launchctl print system/com.apple.sshd
```

`launchctl print gui/$(id -u)/<label>` — Show detailed info about a user service.

```bash
launchctl print gui/$(id -u)/com.apple.Spotlight
```

`launchctl blame system/<label>` — Show why a service is running or not.

```bash
sudo launchctl blame system/com.apple.sshd
```

## Start & Stop (Modern)

`launchctl bootstrap system <plist>` — Load and register a system daemon.

```bash
sudo launchctl bootstrap system /Library/LaunchDaemons/com.example.myservice.plist
```

`launchctl bootout system/<label>` — Unload and deregister a system daemon.

```bash
sudo launchctl bootout system/com.example.myservice
```

`launchctl bootstrap gui/$(id -u) <plist>` — Load a user agent.

```bash
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.myagent.plist
```

`launchctl bootout gui/$(id -u)/<label>` — Unload a user agent.

```bash
launchctl bootout gui/$(id -u)/com.example.myagent
```

`launchctl kickstart -k system/<label>` — Force restart a service (kill and relaunch).

```bash
sudo launchctl kickstart -k system/com.apple.sshd
```

`launchctl kickstart -p system/<label>` — Start a service if it's not running.

```bash
sudo launchctl kickstart -p system/com.example.myservice
```

## Legacy Commands

`launchctl load <plist>` — Load a service (legacy, use bootstrap instead).

```bash
launchctl load ~/Library/LaunchAgents/com.example.myagent.plist
```

`launchctl unload <plist>` — Unload a service (legacy, use bootout instead).

```bash
launchctl unload ~/Library/LaunchAgents/com.example.myagent.plist
```

`launchctl load -w <plist>` — Load and enable a service permanently.

```bash
launchctl load -w ~/Library/LaunchAgents/com.example.myagent.plist
```

`launchctl unload -w <plist>` — Unload and disable a service permanently.

```bash
launchctl unload -w ~/Library/LaunchAgents/com.example.myagent.plist
```

`launchctl start <label>` — Start an already loaded service.

```bash
launchctl start com.example.myagent
```

`launchctl stop <label>` — Stop a running service.

```bash
launchctl stop com.example.myagent
```

## Enable & Disable

`launchctl enable system/<label>` — Enable a system service to start at boot.

```bash
sudo launchctl enable system/com.example.myservice
```

`launchctl disable system/<label>` — Disable a system service from starting at boot.

```bash
sudo launchctl disable system/com.example.myservice
```

`launchctl enable gui/$(id -u)/<label>` — Enable a user agent to start at login.

```bash
launchctl enable gui/$(id -u)/com.example.myagent
```

`launchctl disable gui/$(id -u)/<label>` — Disable a user agent from starting at login.

```bash
launchctl disable gui/$(id -u)/com.example.myagent
```

## Plist Locations

`~/Library/LaunchAgents/` — User agents: run when the user logs in.

```bash
ls ~/Library/LaunchAgents/
```

`/Library/LaunchAgents/` — Global agents: run for all users at login.

```bash
ls /Library/LaunchAgents/
```

`/Library/LaunchDaemons/` — Global daemons: run at boot (as root).

```bash
ls /Library/LaunchDaemons/
```

`/System/Library/LaunchDaemons/` — System daemons (Apple, do not modify).

```bash
ls /System/Library/LaunchDaemons/
```

<!-- PROSE:outro -->
## Conclusion

launchctl bundles the entire service control of macOS into a single command – from a quick `launchctl list` to a targeted restart of an individual daemon. For day-to-day work, reach for the modern syntax with `bootstrap` and `bootout`; the old `load`/`unload` still works but is considered legacy and doesn't understand the domain separation (`system`, `gui`, `user`). The system domain requires `sudo`, and that's exactly where caution pays off: a `bootout` or `disable` on an Apple daemon can break core macOS functionality – so leave the plists under `/System/Library/LaunchDaemons/` alone. When a service misbehaves, `launchctl blame` often points you to the cause faster than digging through logs.

## Further Reading

- [launchd – Apple Developer Documentation](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html) – official guide to creating daemons and agents
- [launchctl(1) – command reference](https://ss64.com/mac/launchctl.html) – overview of all subcommands and options
<!-- PROSE:outro:end -->

## Related Commands

- [caffeinate](https://www.jpkc.com/db/en/cheatsheets/macos/caffeinate/) – prevent the Mac from going to sleep
- [defaults](https://www.jpkc.com/db/en/cheatsheets/macos/defaults/) – read and write macOS settings stored in plists
- [diskutil](https://www.jpkc.com/db/en/cheatsheets/macos/diskutil/) – manage disks, volumes and partitions