Managing macOS Background Services with Homebrew's brew services Command

Desired outcome

You want to start, stop, restart, and inspect a background daemon installed via Homebrew (for example, a database or web server) using the brew services wrapper around launchctl.

Prerequisites

• Homebrew installed (version 2.0 or newer). Run brew --version to confirm.
• The formula you intend to manage ships a launchd plist. Most server‑side formulae (e.g., postgresql, mysql, redis) include one; GUI‑only formulae do not.
• You have write permission to the appropriate LaunchAgents directory:
• For the default Homebrew prefix (/usr/local on Intel or /opt/homebrew on Apple Silicon) user‑services go to ~/Library/LaunchAgents.
• If you installed Homebrew with sudo or use a system‑wide prefix, services belong in /Library/LaunchDaemons and you will need to run the commands with sudo.

Focused procedure

1. List available services

Run the following in a terminal (no special permissions needed for user services):

brew services list

The output shows each formula that provides a plist, its status (started, stopped, error), and the plist file location.

2. Start a service

Choose the formula you want to run, e.g., postgresql. Start it with:

brew services start postgresql

If your Homebrew installation requires root for system services, prefix the command with sudo:

sudo brew services start postgresql

3. Stop a service

brew services stop postgresql

4. Restart a service

brew services restart postgresql

5. View logs

To troubleshoot, fetch the service’s log:

brew services log postgresql

Alternatively, open Console.app and look for the plist label (e.g., homebrew.mxcl.postgresql).

Expected checks

• After starting, run brew services list again. The line for postgresql should show started.
• Verify the launchd job is loaded:

  launchctl list | grep homebrew.mxcl.postgresql

  You should see a entry with a non‑zero PID.

• Confirm the service is reachable. For PostgreSQL, try:

  psql -h localhost -U postgres

  If you get a prompt, the daemon is accepting connections.

• No error messages should appear in the output of brew services start or in the log.

Recovery options

• Inspect the log: If the service fails to start, run brew services log postgresql and look for lines indicating the problem (e.g., missing data directory, port already in use).
• Check dependencies: Ensure any required libraries or other formulae are installed (brew install openssl for PostgreSQL, etc.).
• Restart: Sometimes a transient issue clears with brew services restart postgresql.
• Reinstall the formula: As a last resort, remove and reinstall the formula, which also regenerates the plist:

  brew uninstall postgresql
  brew install postgresql

  Then repeat the start procedure.

• Permission conflicts: Avoid mixing sudo and non‑sudo invocations for the same formula. Stick to one domain (user services in ~/Library/LaunchAgents or system services in /Library/LaunchDaemons) to prevent launchctl from reporting “Operation not permitted” errors.