14 min read | 34 days ago

AdGuard Home is a free , open-source solution that blocks ads and trackers across your entire network. No client software required . Running on your own hardware (like a Raspberry Pi), it acts as a DNS server , rerouting unwanted domains to a “black hole” and protecting your privacy on every device. In this guide, you’ll learn how to set up AdGuard Home , understand its limitations and gotchas, and see how it compares to Pi-hole.

I like to call it your personal AdGuardian —a digital shield for your home network.

Why AdGuard Home?

Already have your Pi set up? Skip to Installing AdGuard Home

• Protects your privacy and blocks ads/trackers for every device on your network—no client software needed.
• Free, open-source, and easy to run on your own hardware.
• Works as a DNS server, rerouting unwanted domains to a “black hole” so your devices never connect to them.
• Built on the same technology as AdGuard’s public DNS, but fully under your control.
• Supports a variety of platforms—AdGuard Home can be installed on Raspberry Pi, Linux, macOS, Windows, and more. There are also add-ons for Home Assistant and an OpenWrt app. See the official getting started guide and the other platforms section for details.

AdGuard Home dashboard overview and features (animated)

Hardware & Prerequisites

Already have your Pi set up? Skip to Installing AdGuard Home

• Raspberry Pi (any model with network access)

  Note: In my case, I am using a Raspberry Pi Zero 2 W H (affiliate link). Any Raspberry Pi model with network access will work, but your experience may vary slightly depending on the hardware.

• microSD card (affiliate link)

See Affiliate Link Disclosure below.

• Power supply
• SSH access to Raspberry Pi
• Access to your router’s DNS settings

Raspberry Pi Zero 2 W H — compact, affordable, and perfect for AdGuard Home projects

Installation Steps

1. Install Raspberry Pi OS

If you’ve already installed Raspberry Pi OS, jump to AdGuard Home installation.

1. Flash the image to your microSD card using Raspberry Pi Imager (recommended):
   • Plug your microSD card into your laptop or computer using a card reader or built-in slot.
   • Download and install Raspberry Pi Imager if you haven’t already.
   • Open the Raspberry Pi Imager application on your computer.
   • In Raspberry Pi Imager, select your Raspberry Pi device, choose the OS you want to install, and select your microSD card as the storage device.
   • Click “Next” to proceed.

   Selecting your Raspberry Pi device in Raspberry Pi Imager

   Tip: (Recommended) When prompted with “Would you like to apply OS customization settings?”, click the “EDIT SETTINGS” button to pre-configure your Pi (hostname, username, Wi-Fi, locale, SSH etc.).

   I call it a Lazy approach! Your Pi will automagically connect to Wi-Fi after successful flashing and will be ready for SSH access right away.

   Choosing the Raspberry Pi OS Customization Prompt in Raspberry Pi Imager

   • Set the hostname
   • Set Username and Password
   • Add Wi-Fi credentials (SSID, Password) and Country
   • Set locale settings (Time Zone)

   OS Customization - General Settings in Raspberry Pi Imager

   • Under the “Services” tab, enable SSH for remote access and then click “SAVE”

   OS Customization - Services Settings to enable SSH in Raspberry Pi Imager

   • This makes your Pi ready to connect to your Wi-Fi network and be accessed via SSH immediately after first boot.
   • You will see a pop up saying “Would you like to apply OS customization settings?”, then, click the “YES” button to write / start flashing the image to your microSD card.

   OS Customization - Apply in Raspberry Pi Imager

   • Wait for the process to complete. It typically takes 5 to 30 mins depending on your microSD card and laptop specs. For me, it took about 5 mins but your mileage may vary!

   Writing workflow in Raspberry Pi Imager (animated)

   • After a successful write, you will see a pop-up prompting - “Write Successful, You can now remove the microSD card from the reader” Write Successful: You can now remove the microSD card from the reader
2. Insert the microSD card into your Raspberry Pi and power it on.
3. If you used OS CUSTOMIZATION, your Pi will auto-connect to Wi-Fi (if set), use your chosen hostname, and have SSH enabled already and ready to ride thru the wild tunnels of SSH. Otherwise, complete the initial setup (locale, Wi-Fi, etc.) via the desktop or SSH.
4. (Optional but Recommended) Update your system:

   sudo apt update && sudo apt upgrade -y
   

2. Install AdGuard Home on Raspberry Pi OS

Need to set up DHCP? Jump to DHCP Server instructions.

1. Set a static IP address for your Pi (Highly Recommended - since AdGuard Home is a server so it needs a static IP address to function properly. Otherwise, at some point your router may assign a different IP address to this device. Also, this step is mandatory if you plan to use AdGuard Home as a DHCP server):

   • List available connections (run the below command to get a list of connection names available to use):

     sudo nmcli con show
     

     
     Output of ‘nmcli con show’ listing available network connections on Raspberry Pi

   • Display a summary of all network interfaces (NICs, for both IPV4 and IPV6 addresses):

     ip a
     

     Output of ‘ip a’ showing network interfaces and IP addresses on Raspberry Pi

   • Set a static IP on Raspberry Pi (run the below command to set a static IP for the existing wireless LAN connection with name as “Preconfigured”):

     sudo nmcli con mod "<your connection name>" ipv4.addresses "<192.168.x.x/24>" ipv4.gateway "<192.168.x.x>" ipv4.dns "<1.1.1.1>" ipv4.method manual
     

     Setting a static IP address for a network connection on Raspberry Pi

   • Reboot the Raspberry Pi to reflect the above change:

     sudo reboot
     

   • Verify the static IP on wlan0 interface to confirm the change:

     ip a
     

     Output of ‘ip a’ showing updated static IP address on Raspberry Pi after reboot

2. Download and run the AdGuard Home installer:

   curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
   

   Running the AdGuard Home installer script on Raspberry Pi

   • The above script also accepts some options:
     • -c <channel> to use a specified channel
     • -r to reinstall AdGuard Home
     • -u to uninstall AdGuard Home
     • -v for verbose output

       Note: Options -r and -u are mutually exclusive.

Configuration & Usage

Basic Configuration

1. Access the AdGuard Home Web Interface:
   • Open a browser and go to http://<your-pi-ip>:3000 (replace <your-pi-ip> with your Raspberry Pi’s IP address).
   • Follow the initial setup wizard if prompted:
     • Set the admin interface username and password for security.
     • Change the Admin web interface port to 80 if port 3000 is already in use.
     • Adjust DNS server listening interfaces if you want AdGuard Home to listen on specific network interfaces.
     • Prompt: Use a static IP address, since AdGuard Home is a server and needs a static IP to function properly. Otherwise, your router may assign a different IP address to this device. Click “Next” to continue.
     • Set the admin interface username and password for security to protect it from unrestricted access. Click “Next” to continue.
     • Prompt: Ensure your Raspberry Pi’s IP address is set as the DNS server for your home network (usually in your router’s DHCP/DNS settings). Click “Next” to continue.

       Note: On many home routers like Netgear, TP-Link etc. operating in “Router Mode” you cannot set a custom DNS server under DHCP settings. In that case, setting up AdGuard Home as a DHCP server will help.

   Netgear Nighthawk RS700 Wi-Fi 7 (affiliate link) — example of a home router where custom DNS settings may be restricted in Router Mode

   See Affiliate Link Disclosure below.

   Netgear Nighthawk RS700 admin portal: DNS server field is not available under DHCP settings in Router Mode

   • Voila! You will be prompted with “Congratulations!” The setup procedure is complete and you’re now ready to start using AdGuard Home. Click “Open Dashboard”. You will then be redirected to http://<your-pi-ip>/login.html

     Note: Admin Web Interface is no longer available on port 3000 and instead is accessible on port 80.

   • Enter your Username and Password and then click “Signin”. Boom! You have now officially landed on the AdGuard Home Dashboard! WooHoo!

   AdGuard Home initial setup and dashboard walkthrough (animated)

   AdGuard Home dashboard — main view after login

2. Set Up DNS:
   • In the AdGuard Home dashboard, go to Settings → DNS settings.
   • Add or remove upstream DNS servers (e.g., Cloudflare, Google, Quad9) as needed.
   • (Optional) Enable DNS-over-HTTPS or DNS-over-TLS for encrypted DNS queries.
   • Ensure your Raspberry Pi’s IP address is set as the DNS server for your home network (usually in your Home router’s DHCP/DNS settings).
3. General Settings:
   • Go to Settings → General settings. Below are optional and are great additions to harden your DNS security:
     • Enable Web Security to check if a domain is blocked by browsing security web service. It will use a privacy-friendly lookup API to perform the check: only a short prefix of the domain name SHA256 hash is sent to the server.
     • Enable Parental Control to block adult websites and enforce safe browsing for kids.

     Side Note: An excellent example of this is when AdGuard Home is installed as a Home Assistant Community Add-on . In this setup, you can write automations in Home Assistant to turn on parental controls when the kids get home or based on any smart home trigger .
     But let’s not go down that Rabbit Hole here! For the sake of this post, we’ll stick with AdGuard Home running directly on your Raspberry Pi. If you’re curious about Home Assistant automations, that’s a whole new adventure for another day!

     • Enable Safe Search to enforce safe search in the following search engines:
       • Bing
       • Duckduckgo
       • Ecosia
       • Google
       • Pixabay
       • Yandex
       • Youtube
   • Review and adjust other options as desired, such as statistics collection (more on that later) or query logging.

   AdGuard Home general settings section

   • Click Save after making changes.
4. Blocklists & Filters:
   • Go to Filters → DNS blocklists.
     • Add or remove blocklists as desired. The defaults are good for most users, but you can add more for stricter blocking. After making changes, click Apply to save.
   • Go to Filters → Custom Filtering Rules.
     • Add or remove custom filtering rules. It employs good old regex syntax, which allows for powerful and flexible matching. After making changes, click Apply to save.

       Note: I can spend all day on just custom filtering rules and it’s meant for advanced use cases. Don’t be afraid by the regex syntax, just try it out and thank me later!

   • Your AdGuard Home instance is now ready to block ads and trackers for all devices using it as their DNS server!

   Custom Filtering Rules section in AdGuard Home

5. Logs and Statistics Retention:
   • Under Settings → General settings → Logs configuration, the default is set to 24 hours. This means the next day you might wake up to find your logs missing. So don’t be surprised! Consider increasing the log retention to 7, 30, or 90 days, depending on your needs.
   • Under Settings → General settings → Statistics configuration, the default is set to 24 hours. Consider increasing the statistics retention to 7, 30, or 90 days, depending on your dashboard needs.

   Log configuration options in AdGuard Home

   Statistics retention settings in AdGuard Home

(Optional) Enable and Configure DHCP Server

Not sure why you need this? See Limitations & Gotchas.

AdGuard Home can act as your network’s DHCP server, which is useful if your router does not allow you to set a custom DNS server for clients.

Before you begin:

• Only enable the DHCP server in AdGuard Home if you disable the DHCP server on your router. Running two DHCP servers on the same network will cause conflicts!

To enable DHCP in AdGuard Home:

1. Go to Settings → DHCP settings in the AdGuard Home dashboard.
2. Toggle Enable DHCP server.
3. Set the IP address range (start and end) for your network (e.g., 192.168.1.100 to 192.168.1.200).
4. Set the gateway IP address (usually your router’s IP, e.g., 192.168.1.1).
5. Set the subnet mask (e.g., 255.255.255.0).
6. Click Save to apply the settings.

DHCP server settings in AdGuard Home

Note: By default, AdGuard Home will use itself as DNS server for the DHCP clients. The default lease time is 24 hours.

After enabling:

• Reboot or reconnect your devices so they receive new IP addresses and DNS settings from AdGuard Home.
• View and manage DHCP leases in the same section.

Tip: Using AdGuard Home as your DHCP server ensures all devices on your network use it for DNS, even if your router doesn’t support custom DNS settings.

Limitations & Gotchas

Curious about alternatives? See AdGuard Home vs. Pi-hole.

Limitations:

Here are some examples of what cannot be blocked by a DNS-level blocker aka AdGuard Home:

• YouTube, Twitch ads;

• Facebook, Twitter, Instagram sponsored posts.

Essentially, any advertising that shares a domain with content cannot be blocked by a DNS-level blocker. Known Limitations

Gotchas:

On many home routers like Netgear, TP-Link etc. operating in “Router Mode” you cannot set a custom DNS server under DHCP settings. In that case, you have two options to ensure all devices use AdGuard Home for DNS:

1. Use your home router in Access Point (AP) mode instead of Router mode. This allows you to set a custom DNS server for your network clients, as the main router (often your ISP’s device) will handle DHCP and routing.
2. Use the DHCP feature of AdGuard Home. Disable DHCP on your router and enable it in AdGuard Home to control DNS assignment. See the section above for details on enabling AdGuard Home’s DHCP server.

AdGuard Home vs. Pi-hole

Both AdGuard Home and Pi-hole block ads and trackers using DNS sinkholing, and both allow you to customize blocklists. However, AdGuard Home provides several features out-of-the-box that Pi-hole requires extra setup or software for:

Note: Some features can be added to Pi-hole with extra software or manual configuration, but AdGuard Home aims to make these easy for all users.

For the latest, see the official comparison.

Conclusion

AdGuard Home on a Raspberry Pi is a powerful, privacy-focused solution for blocking ads and trackers across your entire network. With features like encrypted DNS, parental controls, and flexible filtering, it’s a great alternative to Pi-hole and works well for both beginners and advanced users.

For more details and advanced configuration, check out the official AdGuard Home documentation.

Have questions, tips, or feedback? Leave a comment below or reach out. Your input helps make this guide better for everyone!

Affiliate Link Disclosure

Some links in this guide are Amazon affiliate links. If you purchase through these links, I may earn a small commission at no extra cost to you. Thank you for supporting this guide and helping keep it free and up to date!

Share on:

Read this article on Medium