Zaher Ghaibeh
PHP Backend developer
I've experience in a few PHP Frameworks, such as Laravel, Lumen and Slim (The last two are used for building Microservices/API services).
Using Dnsmasq on macOS for Local Development
Published at Sunday, December 30, 2018 , Categorized under: Development, Docker, Mac, local

I always tried not to install any new services to my local machine, that's why from day one of using Mac (back in 2012) I worked with Vagrant then moved to mish-mash between Vagrant and Docker. However, sometimes you have to install some software that will make your life much easier, and Dnsmasq is one of those apps.

In this article, I am explaining how to install, configure and use Dnsmasq, let's start.

Why you need Dnsmasq

Every day, we edit the hosts file to add the local domain name to it, so that our browsers will be able to communicate with our local code. However, if you have a local DNS server, you can configure it to serve every local request to a specific IP. Moreover, sometimes, you need to have wildcard domain names which are not easy to be done by editing the hosts file, as you will need to add every domain to the file.

When you install Dnsmasq, you will be able to configure it to respond to each and every request you make for a specific tld, for example, you configure it to respond to any domain with the tld .test, which makes your life much more comfortable.

Installing Dnsmasq

Installing Dnsmasq on mac is simple, especially if you are using HomeBrew, so its as simple as running

$ brew install dnsmasq

Once its installed, you can control its status by using one of the following commands:

# To start it
$ sudo brew services start dnsmasq

# To stop it
$ sudo brew services stop dnsmasq

# To restart it
$ sudo brew services restart dnsmasq

Configure Dnsmasq

There are many ways to edit the configuration file for Dnsmasq, the simplest and cleanest one (borrowed from Laravel Valet), is to have a separate file that you can ask Dnsmasq to attach to the main configuration file.

Doing this is simple as the following steps:

  1. Creating a new config directory.
  2. Creating the config file.
  3. Edit Dnsmasq config file.

Since they are simple steps, am not going to explain it with too many details

$ mkdir -p ~/.config/dnsmasq
$ touch  ~/.config/dnsmasq/dnsmasq.conf

We should add the following snippet to the dnsmasq.conf file that we have created:


You can replace .test and .local with whatever tld you like, and if you are using more; you can add them but remember to separate them with a forward slash.

Now we edit the main Dnsmasq config file which located at /usr/local/etc/dnsmasq.conf, but remember that you should be a root to edit this file, then add the following to the end of the file.


Remember to use the absolute path to the file, otherwise it will not work.

Configure the Resolver

In mac, especially the new versions, they have removed the directory /etc/resolver, so we will have to create this one as it will hold the nameserver for each new tld we use in Dnsmasq

$ sudo mkdir -p /etc/resolver

Once we create it, we should create two files here, since remember am configuring Dnsmasq to respond to my .test and .local tlds.

$ touch /etc/resolver/test
$ touch /etc/resolver/local

Then we add the nameserver value to each file, this is the only line they should contain:


And we are done.


Now that we have everything in place, we need to test our configuration:

  1. We need to make sure that Dnsmasq is working, so we run the following commands:
# To start it
$ sudo brew services start dnsmasq

# To stop it
$ sudo brew services stop dnsmasq
  1. We ping a random local domain
$ ping -c 1

And you should get something like (might differ as I've changed the style a bit on my terminal):

PING ( 56 data bytes
 0/  1 ( 0%) lost;    0/   0/   0ms; last:    0ms
 0/  1 ( 0%) lost;    0/   0/   0/   0ms (last 1)
--- ping statistics ---
1 packets transmitted, 1 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 0.048/0.048/0.048/0.000 ms

As you can see the response comes back from

PS: If things didn't work, you might need to either clear the DNS cache or restart your computer, choose the simplest one for you.

Watch a video

If you are a video person, you can watch the whole process on youtube just click the image:

Install and configure Dnsmasq for local development on mac


As you can see Dnsmasq has many features that we can benefit from, however, those are out of the scope of this article; you can check the documentation if you are interested in knowing more about it.

So from now on, there is no need any more to edit your /etc/hosts file any more, configure your code and work, with no limit to what is the requirements for your project, even if its a wildcard domain (subdomain) feature.

Share It via: