How to Manage launchd Services via Command Line: Start, Stop, Restart (MacOS)


2 views

On macOS, launchd is the system's service management framework, responsible for starting, stopping, and managing daemons and agents. Unlike Linux's systemd or Debian's invoke-rc.d, macOS uses launchctl as the primary command-line tool for interacting with launchd.

Here are the fundamental commands for managing services:

# Start a service
launchctl load /Library/LaunchDaemons/com.example.service.plist

# Stop a service
launchctl unload /Library/LaunchDaemons/com.example.service.plist

# Restart a service (unload then load)
launchctl unload /Library/LaunchDaemons/com.example.service.plist && launchctl load /Library/LaunchDaemons/com.example.service.plist

For common services like Apache (httpd) or Apple File Protocol (afpd):

# Restart Apache
sudo launchctl unload /System/Library/LaunchDaemons/org.apache.httpd.plist
sudo launchctl load /System/Library/LaunchDaemons/org.apache.httpd.plist

# Manage AFP service
sudo launchctl unload /System/Library/LaunchDaemons/com.apple.AppleFileServer.plist
sudo launchctl load /System/Library/LaunchDaemons/com.apple.AppleFileServer.plist

For more control over service states:

# List all loaded services
launchctl list

# Check status of specific service
launchctl list | grep httpd

# Enable service to start at boot
sudo launchctl enable system/org.apache.httpd

# Disable service from starting at boot
sudo launchctl disable system/org.apache.httpd

For user-created or third-party services, you'll typically find their plist files in these locations:

# System-wide daemons
/Library/LaunchDaemons/

# User-specific agents
~/Library/LaunchAgents/

# macOS system daemons
/System/Library/LaunchDaemons/
  • Always use sudo for system-level services
  • Check service logs in Console.app or via log show --predicate 'process == "httpd"' --last 1h
  • Verify plist syntax with plutil -lint /path/to/service.plist
  • For GUI services, you may need to restart the entire WindowServer process

Recent macOS versions (10.10+) have updated launchctl syntax. The new bootstrap system uses:

# New syntax for starting services
launchctl bootstrap system /Library/LaunchDaemons/com.example.service.plist

# New syntax for stopping
launchctl bootout system /Library/LaunchDaemons/com.example.service.plist

# Target specific domain (system/gui/user)
launchctl enable user/501/com.example.agent

On macOS, launchd is the system's service management framework, responsible for starting, stopping, and managing daemons, applications, and scripts. Unlike Linux's systemd or Debian's invoke-rc.d, macOS relies on launchctl for service control.

To manage services (called "jobs" in launchd terminology), use the launchctl command-line tool. Here are the core operations:

# Start a service
launchctl start com.example.service

# Stop a service
launchctl stop com.example.service

# Restart a service (stop + start)
launchctl stop com.example.service && launchctl start com.example.service

macOS distinguishes between system-level and user-level services:

# System-wide services (requires sudo)
sudo launchctl load /Library/LaunchDaemons/com.example.plist
sudo launchctl unload /Library/LaunchDaemons/com.example.plist

# User-level services
launchctl load ~/Library/LaunchAgents/com.example.plist
launchctl unload ~/Library/LaunchAgents/com.example.plist

For the specific services mentioned in the question:

# Apache HTTP Server (httpd)
sudo launchctl stop org.apache.httpd
sudo launchctl start org.apache.httpd

# Apple Filing Protocol (afpd)
sudo launchctl stop com.apple.AppleFileServer
sudo launchctl start com.apple.AppleFileServer

For more control over services:

# List all loaded services
launchctl list

# Check status of a specific service
launchctl list | grep httpd

# Enable a service to start at boot
sudo launchctl enable system/com.example.service

# Disable a service from starting at boot
sudo launchctl disable system/com.example.service

In newer macOS versions (10.10+), you might need to use:

# For complete service removal
sudo launchctl bootout system/com.example.service

# Instead of the traditional
sudo launchctl unload /Library/LaunchDaemons/com.example.plist

When services fail to start/stop properly:

# View system logs for a service
log show --predicate 'process == "httpd"' --last 1h

# Get detailed error information
sudo launchctl debug system/com.example.service

For completeness, here's how to create a simple launchd service:

# Sample plist file (/Library/LaunchDaemons/com.example.myservice.plist)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.myservice</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/myservice</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Remember to set proper permissions after creating a new service:

sudo chown root:wheel /Library/LaunchDaemons/com.example.myservice.plist
sudo chmod 644 /Library/LaunchDaemons/com.example.myservice.plist