How To Install Pi-hole on a Headless Raspberry Pi

Enable network-wide ad blocking with Pi-hole.

It might come as a surprise, but I don’t really mind internet ads.

What I do mind, though, is how internet ads work today. To present you with relevant ads, the advertisement companies will track your every move on the internet. You might think that the sites you visit are isolated from each other, but ad trackers keep following you around everywhere you click.

That’s why I use EFF’s Privacy Badger, a browser extension that blocks tracking cookies. By blocking this horrendous cookies, you fall off the advertiser’s radar. Because of this, I see very few ads on the internet. So Privacy Badger solves the problem for me.

But there are more people in our household that use the internet. Installing the browser extension on every device isn’t really feasible, and there is a lot of trackers that Privacy Badger won’t block. Mobile app advertisements is a good example. The ads shown in the apps my oldest kid plays on their tablet also track their every move.

So it’s better to attack the problem at its core.

This is where Pi-hole comes in. Pi-hole enables network-wide ad blocking. Configured as a DNS service, it will check every internet address that is accessed through the local network against a set of blacklists of known trackers. If the address is on one of the lists, the DNS request is blocked, and the tracker will receive no information.

With Pi-hole, everyone who is using our Wi-Fi access point are protected from pesky ad trackers.

How to Install Pi-hole

This guide will take you through the entire process of installing Pi-hole on a headless, fresh-out-of-the-box, Raspberry Pi.

You’ll need an Internet connection, a Raspberry Pi, a power adapter for the Pi, a compatible microSD memory card, a microSD card reader, a network cable, an available network cable port in your router, and access to your router’s web interface.

Installing Raspbian

The first thing we need to do is to install an operating system on the Raspberry Pi. The OS of choice is Raspbian, which is tailored for the Pi.

Warning: All the contents of the microSD card you use will be deleted when we install Raspbian. Make sure you haven’t stored anything important on it. As a rule of thumb, an SD card is generally a bad place to store anything important.

  1. Download a version of Raspbian from the official download page. The Raspbian Buster Lite edition is sufficient.
  2. Insert the microSD card into the card reader, and connect the card reader to your computer if necessary.
  3. The next step is to write the OS to the microSD card. To do this we need a writing tool like balenaEtcher, which is available for Windows, macOS, and Linux.
  4. Download the latest version of balenaEtcher and install it.
  5. Open balenaEtcher and select, from your hard drive, the Raspberry Pi .zip file you wish to write to the microSD card.
  6. Select the microSD card you wish to write your image to.
  7. Review your selections and click “Flash!” to begin writing data to the microSD card.
  8. The writing process might take several minutes to finish.

Source: Installing operating system images - Raspberry Pi Documentation

Enabling SSH

Since this is a headless install, i.e. we’re doing it without a keyboard and a monitor connected to the Raspberry Pi, we need another way to send commands to it. We’ll use an SSH connection, but for security reasons, SSH is not enabled by default in Raspbian. Enabling it is simple, though.

SSH can be enabled by placing a file named ssh, without any extension, onto the boot partition of the SD card from another computer. When the Pi boots, it looks for the ssh file. If it is found, SSH is enabled and the file is deleted. The content of the file does not matter; it could contain text, or nothing at all.

The microSD card we installed Raspbian on in the previous section has two partitions. The first one, which is the smaller one, is the boot partition. Place the file into this one.

Source: SSH (Secure Shell) - Raspberry Pi Documentation

Booting the Raspberry Pi

With Raspbian installed on the microSD card, and SSH enabled, it’s time to boot up the Raspberry Pi for the first time.

  1. Move the microSD card from the card reader to the Raspberry Pi’s microSD card slot.
  2. Hook the Raspberry Pi up with the network cable, and connect it to your router.
  3. Connect the Raspberry Pi to the power adapter.
  4. The Pi has no power switch, and will boot automatically as soon as it’s connected to a power source. You won’t hear any sounds, but some light should be flashing on the Raspberry Pi.
  5. To connect to the Raspberry Pi via SSH, we need to figure out what what IP address it was assigned by your router. How this is done will depend on what router you are using. But in general you can find the IP address by logging in to the routers web interface and look for “DHCP leases” or something similar.
  6. Find the device with host name “raspberrypi”, and note its IP address.

Connecting to the Raspberry Pi

How you connect to the Raspberry Pi over SSH will depend on which operating system you are using on your computer.

SSH is built into Linux distributions and Mac OS, and is an optional feature in Windows 10. For older Windows versions and mobile devices, third-party SSH clients are available. On Windows, a good choice of SSH client is Putty.

With your SSH client of choice, you can now connect to the Raspberry Pi. The default username is pi, and default password is raspberry.

Raspbian hardening

The Raspberry Pi will not be accessible from the Internet by default if you follow this guide. But we’ll still be doing some hardening just in case. You can skip this section and jump to the next, but I strongly recommend you don’t.

Change the default password

Once you’re logged in as the pi user, it is highly advisable to use the passwd command to change the default password to improve your Pi’s security.

Enter passwd on the command line and press Enter. You’ll be prompted to enter your current password to authenticate, and then asked for a new password. Press Enter on completion and you’ll be asked to confirm it. Note that no characters will be displayed while entering your password. Once you’ve correctly confirmed your password, you’ll be shown a success message (passwd: password updated successfully), and the new password will apply immediately.

Source: Linux users - Raspberry Pi Documentation

Create a new user

Instead of using the pi user to log in to the Raspberry Pi, you should create a new user.

  1. Enter sudo adduser bob and you’ll be prompted for a password for the new user bob. It’s advisable that you replace bob with something else that’s easier to remember, like your own first name. If your name is actually Bob, then you’re all good to go.
  2. Next, add the new user to the sudo group with the adduser command: sudo adduser bob sudo. Again, replace bob with the name of the user you created in the previous step.
  3. Log out of the current SSH session with the logout command.
  4. Log in to the Raspberry Pi again over SSH with the new user you just created.

It might be tempting to delete the pi user. This is possible, but not recommended. In the current Raspbian distribution (as of 2020-01-01), there are some aspects that require the pi user to be present.

Source: Linux users - Raspberry Pi Documentation, Securing your Raspberry Pi - Raspberry Pi Documentation

Installing Pi-hole

The Raspberry Pi is ready to have the Pi-hole installed. And it’s as easy as, well, pie.

  1. Run the command curl -sSL | bash
  2. Follow the on-screen instructions. Which options you want to chose depend on your ad blocking needs, but I chose the following for my install:
    1. Interface eth0 (since it’s a cabled connection).
    2. Upstream DNS provider: Cloudflare (they are fast and not evil (yet)).
    3. All the third party blocklists.
    4. Selected both the ipv4 and ipv6 protocols
    5. Gave the Raspberry Pi a static IP so we can use it as a DNS server. Exactly what IP you should give it depends on your network setup. Make sure it’s not within the range of IP addresses your routers DHCP server serves dynamic IP addresses from. In my case, the first dynamic IP is, which means I can give the Pi any address below that (except for addresses that is already assigned, of course.)
    6. Installed the web admin interface.
    7. Installed the web server.
    8. Turned query logging on.
    9. Opted to show everything on the logs.
  3. At the end of the install, you’ll see a summary. Write down both the IP address and the web admin interface password.
  4. The Pi-hole web admin interface should now be accessible at http://<IP_ADDPRESS_OF_YOUR_PI_HOLE>/admin/.

Use Pi-hole as your DNS server

The final step is to configure your router so that it uses and announces the Pi-hole as your home network’s DNS server. Again, how this is done depends on your router. But how I did it on my router running OpenWrt might indicate how you do this on your own router.

  1. After logging in to OpenWrt on your router, go to Network -> Interfaces -> LAN.
  2. In the Use Custom DNS Server field, add the static IP address of the Raspberry Pi.
  3. Click Save & Apply.
  4. If you’re using IPv6, you also have to configure the Pi-hole as the DNS server for that protocol. In OpenWrt this is done by going to Network -> Interfaces -> LAN -> IPV6 Settings.
  5. In the Announced DNS servers field add the IPv6 address of Pi-hole. You’ll find the address in the Pi-hole’s web admin interface under the settings menu option. Please note that you have to be logged in to the web admin interface to see this menu option.
  6. Click Save & Apply.
  7. The Pi-hole admin interface should now be accessible on http://pi.hole/admin/.
  8. You might have to renew your computer’s IP-address for the new settings to become active.

If this makes absolutely no sense to you, the Pi-hole post-install instructions have more information on how to configure it as a DNS server.

Wrapping up

Well, that was a tad complicated, but you can now access your favorite sites without seeing all those privacy violating advertisements.

One limitation of the current setup is that the ad trackers will only be blocked for clients that are connected to your local network. As soon as you’re outside your Wi-Fi access point’s range, you’re also out of the Pi-hole’s range.

This can be solved by using a private VPN connection together with the Pi-hole, but that’s not a topic covered by this guide. If you’re curious about that kind of setup, the official Pi-hole VPN documentation is a good place to start.

When the advertisers stop tracking us everywhere1, we can turn off the Pi-hole and use the Raspberry Pi for something else.

If you end up installing and find Pi-hole useful, please consider donating to the project as per my recent post, Support Your Favorite Creators Today.

  1. Haha. ↩︎


Do you have any thoughts you want to share? A question, maybe? Or is something in this post just plainly wrong? Then please send an e-mail to vegard at vegard dot net with your input. You can also use any of the other points of contact listed on the About page.


It looks like you're using Google's Chrome browser, which records everything you do on the internet. Personally identifiable and sensitive information about you is then sold to the highest bidder, making you a part of surveillance capitalism.

The Contra Chrome comic explains why this is bad, and why you should use another browser.