---
title: Starting and stopping background services with Homebrew
teaser: Don't fiddle with `launctl` when there's a better way.
tags: osx
author: Gabe Berke-Williams
published_on: 2014-01-21
---

> editor's note (August 4, 2023): New versions of MacOS and homebrew means
> the information in this article is no longer current.
>
> If you are on a version of MacOS Ventura or later, [see this post][updated-homebrew-post]
> for further information. If your version of MacOS is pre-Ventura...read on!

I love [Homebrew][homebrew], but sometimes it really gets me down, you know?
Especially when I have to deal with [`launchctl`][launchctl].

`launchctl` loads and unloads services that start at login. In OS X, these
services are represented by files ending with `.plist` (which stands for
"property list"). These plists are usually stored in either
`~/Library/LaunchAgents` or `/Library/LaunchAgents`. You load them (i.e. tell
them to start at login) with `launchctl load $PATH_TO_LIST` and unload them with
`launchctl unload $PATH_TO_LIST`. Loading a plist tells the program it
represents (e.g. `redis`) to start at login, while unloading it tells the
program not to start at login.

This post-install message from Homebrew may look familiar:

<pre>
<samp>To have launchd start mysql at login:
    ln -sfv /usr/local/opt/mysql/&#42;.plist ~/Library/LaunchAgents
Then to load mysql now:
    launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist
Or, if you don't want/need launchctl, you can just run:
    mysql.server start</samp>
</pre>

Doing all that takes too long, and I can never remember where Homebrew plists
are. Fortunately, Homebrew includes a lovely interface for managing this without
using `ln`, `launchctl` or knowing where plists are.

## brew services

First, install `brew services` by tapping `homebrew/services` (one time):

```bash
brew tap homebrew/services
```

Here's an example usage:

```sh
$ brew services start mysql
==> Successfully started `mysql` (label: homebrew.mxcl.mysql)
```

Behind the scenes, `brew services start` is doing everything in the post-install
message above. First it runs `ln -sfv ...` for you. Then it runs `launchctl load
~/Library/LaunchAgents/homebrew.mxcl.mysql.plist`. It Just Works.

Let's say MySQL's acting funky. We can easily restart it:

```bash
brew services restart mysql
Stopping `mysql`... (might take a while)
==> Successfully stopped `mysql` (label: homebrew.mxcl.mysql)
==> Successfully started `mysql` (label: homebrew.mxcl.mysql)
```

Now let's see everything we've loaded:

```bash
$ brew services list
redis      started      442 /Users/gabe/Library/LaunchAgents/homebrew.mxcl.redis.plist
postgresql started      443 /Users/gabe/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
mongodb    started      444 /Users/gabe/Library/LaunchAgents/homebrew.mxcl.mongodb.plist
memcached  started      445 /Users/gabe/Library/LaunchAgents/homebrew.mxcl.memcached.plist
mysql      started    87538 /Users/gabe/Library/LaunchAgents/homebrew.mxcl.mysql.plist
```

Note that the list of services includes services you started with `launchctl
load`, not just services you loaded with `brew services`.

Let's say we uninstalled MySQL and Homebrew didn't remove the plist for some
reason (it usually removes it for you). There's a command for you:

```bash
$ brew services cleanup
Removing unused plist /Users/gabe/Library/LaunchAgents/homebrew.mxcl.mysql.plist
```

Kachow.

## Hidden Homebrew commands

Homebrew ships with a whole bunch of commands that don't show up in `brew
--help`. You can see a list of them in [the Homebrew git repo][cmd]. Each file
is named like `brew-COMMAND`, and you run them with `brew command`. I recommend
`brew beer`.

[cmd]: https://github.com/Homebrew/homebrew-boneyard/tree/master/cmd

## What's next

If you liked this, I recommend reading through Homebrew's [Tips and
Tricks][tips-and-tricks]. You can also try out another Homebrew extension for
installing Mac apps: [homebrew-cask][cask].

[homebrew]: http://brew.sh/
[launchctl]: https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/launchctl.1.html
[humble]: https://thoughtbot.com/blog/the-unix-shells-humble-if
[tips-and-tricks]: https://github.com/Homebrew/homebrew/wiki/Tips-N%27-Tricks
[cask]: https://github.com/phinze/homebrew-cask
[updated-homebrew-post]: https://thoughtbot.com/blog/as-managing-background-processes-in-ventura