> ## Content Index > Fetch the complete content index at: https://blog.harshkohli.com/llms.txt > Use this file to discover other available public pages before exploring further. # Pi-hole + WireGuard on Raspberry Pi: Full Setup Guide - URL: https://blog.harshkohli.com/raspberry-pi-pihole-wireguard-vpn-setup/ - Published: 2026-10-21T08:19:49.000Z - Updated: 2026-10-23T03:50:05.000Z - Description: Set up Pi-hole on a Raspberry Pi to block ads on every device, then add a free WireGuard or Tailscale VPN. Includes a CGNAT fix. - Author: Harsh Kohli - Tags: Guides, How-To, PC & Hardware *Updated October 2026\. Checked against the current releases: Pi-hole core v6.5 (FTL v6.8), PiVPN v4.11.1 with WireGuard, Tailscale 1.104, and Raspberry Pi OS Lite 64-bit (the 2026-10-06 image, based on Debian Trixie; the steps also work on Bookworm). Steps are the same on a Pi 4, Pi 5 or Zero 2 W.* A Raspberry Pi sitting next to the router is honestly one of the most useful things you can have at home. It sips power, it stays on all the time, and once it's set up you mostly forget it exists. Except you'll notice the ads are gone. On every device. Even the smart TV. This guide covers the whole thing from an empty microSD card: flashing the OS, getting Pi-hole running for network-wide ad blocking, and then adding a WireGuard VPN so you can use Pi-hole (and your home network) from your phone on mobile data. No paid services anywhere. And if port forwarding just refuses to work, which happens a lot on Starlink, T-Mobile Home Internet, Jio and Airtel, there's a Tailscale section for exactly that. I've written it for people who haven't touched Linux much. If you have, skim the first half. **Jump to:** - [What you need](#what-you-need-hardware-list) - [Flash Raspberry Pi OS Lite](#step-1-flash-raspberry-pi-os-lite-with-raspberry-pi-imager) - [First SSH login](#step-2-ssh-into-the-raspberry-pi) - [Give the Pi a fixed IP](#step-4-set-a-static-ip-on-the-raspberry-pi) - [Install Pi-hole v6](#step-5-install-pi-hole-v6-on-raspberry-pi) - [Point your network at Pi-hole](#step-6-use-pi-hole-as-dns-for-your-whole-network) - [WireGuard VPN with PiVPN](#step-8-set-up-a-wireguard-vpn-with-pivpn) - [CGNAT (no port forwarding)](#cgnat-when-port-forwarding-wont-work-starlink-t-mobile-jio-airtel) - [Tailscale (no port forwarding)](#tailscale-alternative-no-port-forwarding-works-behind-cgnat) - [Add your phone](#step-11-add-your-phone-to-wireguard-with-a-qr-code) - [Troubleshooting](#pi-hole-and-pivpn-troubleshooting) - [FAQ](#faq) ## What you need (hardware list) The official Raspberry Pi parts are sold through approved resellers, and the Raspberry Pi site lists them by country. I've left exact prices out because they change every week. Roughly, a Pi 4 4GB, power supply and card come to somewhere around $80 to $100 in the US or ₹6,000 to ₹8,000 in India, depending on stock. - **A Raspberry Pi.** Any of these will do: - *Pi Zero 2 W.* Enough for Pi-hole plus a VPN for a normal household. It's Wi-Fi only unless you add a USB Ethernet adapter, which I'd recommend. Stock for it keeps coming and going, so check an official Raspberry Pi reseller (the Raspberry Pi site lists them by country). - *Pi 4, 2 GB or 4 GB.* The sweet spot in my opinion. Gigabit Ethernet and plenty of headroom for other stuff later. The 4 GB board: Raspberry Pi 4 Model B 4GB ([official page](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/?ref=blog.harshkohli.com)). - *Pi 5.* Overkill for just this, but nice if you plan to run more services on it later: Raspberry Pi 5 8GB ([official page](https://www.raspberrypi.com/products/raspberry-pi-5/?ref=blog.harshkohli.com)). - **A proper power supply.** Use the official one if you can. Cheap phone chargers cause random reboots and SD card corruption, and that's a pain to debug. The Pi 4 needs 5V 3A, so get the plug type for your country: official 15W USB-C supply ([official page](https://www.raspberrypi.com/products/type-c-power-supply/?ref=blog.harshkohli.com)). The Pi 5 wants 5V 5A: official 27W USB-C supply ([official page](https://www.raspberrypi.com/products/27w-power-supply/?ref=blog.harshkohli.com)). - **A microSD card** from a known brand, 32 GB or more, A1 or A2 rated. I'd go with something like the SanDisk Extreme 64GB. 64 GB is way more than Pi-hole needs, but it's often barely more expensive than 32. - **An Ethernet cable** to plug the Pi into your router. Wi-Fi works, but for something your whole network depends on, a cable is just more reliable. - **A case.** Optional but a good idea. For the Pi 5 the official Pi 5 case ([official page](https://www.raspberrypi.com/products/raspberry-pi-5-case/?ref=blog.harshkohli.com)) has a fan built in. On a Pi 4 any decent case with a small heatsink is fine. You'll also need a computer with a card reader and access to your router's admin page. ![Top view of a Raspberry Pi 4 Model B board showing the USB, Ethernet and GPIO pins](https://blog.harshkohli.com/content/images/2026/10/raspberry-pi-4-model-b-top-view.webp) Raspberry Pi 4 Model B. Photo: [Laserlicht](https://commons.wikimedia.org/wiki/File:Raspberry%5FPi%5F4%5FModel%5FB%5F-%5FTop.jpg?ref=blog.harshkohli.com), [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/?ref=blog.harshkohli.com) ![Raspberry Pi 5 board with the official active cooler fitted](https://blog.harshkohli.com/content/images/2026/10/raspberry-pi-5-active-cooler.webp) Raspberry Pi 5 with the official active cooler. Photo: [SimonWaldherr](https://commons.wikimedia.org/wiki/File:Raspberry%5FPi%5F5%5Fwith%5Factive%5Fcooler.jpg?ref=blog.harshkohli.com), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/?ref=blog.harshkohli.com) ![Raspberry Pi Zero 2 W, a small board that is enough for Pi-hole and a WireGuard VPN](https://blog.harshkohli.com/content/images/2026/10/raspberry-pi-zero-2-w-board.webp) Raspberry Pi Zero 2 W. Photo: [Anil Öztas](https://commons.wikimedia.org/wiki/File:Raspberry%5FPi%5FZero%5F2%5FW%5F--%5F2024%5F--%5F0012.jpg?ref=blog.harshkohli.com), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/?ref=blog.harshkohli.com) ## Step 1: Flash Raspberry Pi OS Lite with Raspberry Pi Imager We don't need a desktop on this thing, so we'll use **Raspberry Pi OS Lite (64-bit)**. Less stuff running, fewer updates. 1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/?ref=blog.harshkohli.com) on your PC and open it. 2. Choose your Pi model, then the OS: *Raspberry Pi OS (other)* → *Raspberry Pi OS Lite (64-bit)*. On a Zero 2 W, the 64-bit Lite image is fine too. 3. Pick your microSD card as the storage. 4. When it asks about OS customisation, say yes and fill these in: - Hostname: something like `pihole` - Username and a strong password. Don't leave it as the defaults. - Wi-Fi name and password (only if you're not using a cable), and set the Wi-Fi country to where you live (US, IN and so on). - Locale and timezone for your area, like America/New\_York or Asia/Kolkata. - Enable SSH with password authentication. You can switch to key-based login later. 5. Write the card. It takes a few minutes and verifies itself afterwards. Put the card in the Pi, connect Ethernet, then plug in power. Give it a couple of minutes on first boot. It resizes the filesystem and applies your settings, so don't panic if nothing seems to happen at first. ## Step 2: SSH into the Raspberry Pi From your PC (Windows Terminal, PowerShell, or a Mac/Linux terminal): ``` ssh yourusername@pihole.local ``` If `pihole.local` doesn't resolve, open your router's admin page, look at the connected devices list, find the Pi's IP and use that instead: ``` ssh yourusername@192.168.1.50 ``` Type `yes` to accept the fingerprint, enter your password, and you're in. ## Step 3: Update everything Always do this first on a fresh install: ``` sudo apt update sudo apt full-upgrade -y sudo reboot ``` Wait a minute and SSH back in. ## Step 4: Set a static IP on the Raspberry Pi This part matters. Every device on your network is going to ask the Pi for DNS, so if its IP changes one day, your whole internet "breaks" and you'll be confused for a while. It's one of the most common mistakes. The cleanest way is a **DHCP reservation** on the router. Every router calls it something different: Address Reservation, Static Lease, Bind IP to MAC, and so on. You'll usually find it under LAN or DHCP settings. Pick the Pi from the list and lock it to its current IP. Check the Pi's IP and interface name with: ``` hostname -I ip -br addr ``` If your router (some ISP-supplied ones are pretty locked down) doesn't allow reservations, you can set a static IP on the Pi itself. Recent Raspberry Pi OS uses NetworkManager, so: ``` sudo nmtui ``` Go to *Edit a connection*, pick your wired connection, switch IPv4 to *Manual*, and enter the address (like `192.168.1.50/24`), your router as the gateway, and a DNS server like `1.1.1.1` for now. Pick an address outside the router's DHCP range so nothing else grabs it. ## Step 5: Install Pi-hole v6 on Raspberry Pi The official one-liner: ``` curl -sSL https://install.pi-hole.net | bash ``` Piping a script from the internet into bash makes some people nervous, and fair enough. If you'd rather read it first: ``` curl -sSL https://install.pi-hole.net -o pihole-install.sh less pihole-install.sh sudo bash pihole-install.sh ``` The installer is a bunch of blue screens. Mostly you can accept the defaults: - It'll remind you that you need a static IP. We did that already. - Upstream DNS: pick whatever you like. Cloudflare or Quad9 are good choices. - Keep the default blocklist. - Install the web interface and turn on query logging. You'll want the stats. At the end it shows the admin page address and a password. Pi-hole v6 has its own built-in web server now (no more lighttpd), so the dashboard lives at: ``` http://192.168.1.50/admin ``` ![Pi-hole v6 web dashboard showing total queries, queries blocked, percentage blocked and domains on lists](https://blog.harshkohli.com/content/images/2026/10/pi-hole-v6-dashboard-screenshot.webp) The Pi-hole v6 dashboard. Screenshot: [Pi-hole, via Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Pi-Hole%5F6%5Fscreenshot%5F%286.1.2%29.png?ref=blog.harshkohli.com), public domain To set your own password instead of the random one: ``` pihole setpassword ``` Small note if you're following an older tutorial: in v6 a lot changed. The settings live in `/etc/pihole/pihole.toml` now, and the old `setupVars.conf` and `pihole -a -p` stuff is gone. Most things you'll want to change are in the web UI under Settings anyway, so I'd just use that rather than editing the file by hand. The [official Pi-hole docs](https://docs.pi-hole.net/?ref=blog.harshkohli.com) are good if you want the details. ## Step 6: Use Pi-hole as DNS for your whole network Pi-hole only blocks stuff for devices that actually use it as DNS. You've got two options. **Option A, the router (best).** In your router's DHCP/LAN settings, set the primary DNS server to the Pi's IP. Leave the secondary empty, or set it to the Pi again. If you put 8.8.8.8 as secondary, devices will happily skip Pi-hole half the time and you'll wonder why ads still show up. Then reconnect your devices (or toggle Wi-Fi off and on) so they pick up the new DNS. **Option B, Pi-hole does DHCP.** A lot of ISP routers don't let you change the DNS they hand out. Plenty of Jio and Airtel units are like that, and so are the Xfinity and AT&T gateways in the US. If that's you, turn off DHCP on the router, then turn it on in Pi-hole under *Settings → DHCP*. Do this carefully, because if both are on, or both are off, things get messy fast. To check it's working, open the Pi-hole dashboard. You should see queries coming in from your devices within a minute or two. From a Windows PC you can also run: ``` nslookup doubleclick.net ``` If the server shown is your Pi's IP and the answer is `0.0.0.0`, it's blocking. ## Step 7: Best Pi-hole blocklists (without going overboard) The default list is fine for most people. If you want more, go to *Lists* in the dashboard, paste a list URL, add it, and then update gravity: ``` pihole -g ``` A couple I think are worth it: - HaGeZi's lists (the "Multi PRO" one is a good balance): `https://raw.githubusercontent.com/hagezi/dns-blocklists/main/adblock/pro.txt` - OISD big: `https://big.oisd.nl` Honest opinion: more lists does not mean better. Stack ten giant lists and you'll start breaking login pages, payment gateways and random apps, and then the family complains. Start small. If something breaks, check the Query Log, find the blocked domain and allow it. ## Step 8: Set up a WireGuard VPN with PiVPN Pi-hole is great at home. The moment you're on mobile data though, you lose it. A VPN back to your house fixes that, and you also get access to anything else on your home network. (If all you want is ad blocking on an Android phone, without a Pi at all, the built-in [Private DNS setting](https://blog.harshkohli.com/private-dns-android-block-ads/) gets you most of the way.) The easiest way to set up WireGuard on a Pi is still PiVPN: ``` curl -L https://install.pivpn.io | bash ``` A heads-up: PiVPN's original maintainer stepped back in 2024 and the project now says it's maintained on a "best-effort" basis. It still works fine for WireGuard, and WireGuard itself gets updated through normal system updates, but don't expect quick fixes if something breaks. That's partly why there's a [Tailscale section](#tailscale-alternative-no-port-forwarding-works-behind-cgnat) further down. PiVPN's own docs are at [docs.pivpn.io](https://docs.pivpn.io/?ref=blog.harshkohli.com). Go through the installer: - Choose **WireGuard**, not OpenVPN. OpenVPN still works, but WireGuard is quicker and your phone battery will thank you. - Port: just leave it at **51820** (UDP) unless you have a reason not to. - The DNS question is the important one. PiVPN notices Pi-hole is already installed and offers it. Say yes, because that's what makes ads get blocked on your phone outside the house too. - Then it asks public IP or DNS name. No DuckDNS hostname yet? Pick the IP for now, it's easy to change later after you do Step 10. - Unattended upgrades: yes. Something exposed to the internet should get security updates on its own. Reboot when it's done. ## Step 9: Port forward UDP 51820 on your router Now tell the router where VPN traffic should go. Look for *Port Forwarding* (sometimes "Virtual Server" or "NAT") and add a rule: - Protocol: **UDP** - External port: **51820** - Internal IP: your Pi's IP - Internal port: **51820** Only forward this one port. Do not forward 80 or 22 to the Pi. There's no reason to expose the dashboard or SSH to the internet when you have a VPN. ## Step 10: Free dynamic DNS with DuckDNS Your home IP isn't fixed on most plans. Restart the router and there's a decent chance it's different. So instead of typing an IP into your phone's VPN config, you use a free hostname that keeps itself updated. [DuckDNS](https://www.duckdns.org/?ref=blog.harshkohli.com) is free and dead simple. Sign in, create a subdomain like `myhomepi.duckdns.org`, and copy your token. Then on the Pi: ``` mkdir -p ~/duckdns nano ~/duckdns/duck.sh ``` Paste this, with your own subdomain and token: ``` echo url="https://www.duckdns.org/update?domains=myhomepi&token=YOUR-TOKEN&ip=" | curl -k -o ~/duckdns/duck.log -K - ``` Make it executable and run it every 5 minutes: ``` chmod 700 ~/duckdns/duck.sh crontab -e ``` Add this line at the bottom: ``` */5 * * * * ~/duckdns/duck.sh >/dev/null 2>&1 ``` Run it once by hand and check that `~/duckdns/duck.log` says `OK`. Quick tip, a few routers have DuckDNS or No-IP under DDNS settings already. If yours does, skip the script and just use that. If you picked your raw IP in PiVPN earlier, change the `Endpoint` line in your client configs, or just rerun the installer and choose the hostname this time. ## CGNAT: when port forwarding won't work (Starlink, T-Mobile, Jio, Airtel) Most tutorials skip this part, and it catches a lot of people out. Some ISPs don't give you your own public IPv4 address. You sit behind **CGNAT**, which basically means a whole bunch of customers share one IP. Then port forwarding does nothing. You can set up the rule perfectly and still get zero handshakes, which is super frustrating the first time. Who does this? In the US, Starlink and T-Mobile Home Internet are the usual ones, and Verizon's 5G Home Internet often is too. Regular cable and fiber plans like Comcast Xfinity, AT&T Fiber and Verizon Fios normally do give you a public IP, so port forwarding should work there. In India, Jio Fiber and Airtel Xstream often put you behind CGNAT, though it depends on your area and plan. How to check: open the router's status page and note the WAN IP. Now google "what is my IP" and compare. If they're different, or the WAN IP starts with `100.64` to `100.127`, `10.`, or `172.16` to `172.31`, you're behind CGNAT. Your options: - Ask the ISP for a public IP. Some will do it for free if you ask nicely, some charge for a static IP, some just say no. Starlink, for example, only gives a public IP on certain business plans. - Use **Tailscale**. This is what I'd do, and it gets its own section right below. No port forwarding, doesn't care about CGNAT. ## Tailscale alternative (no port forwarding, works behind CGNAT) Under the hood it's WireGuard too. The difference is Tailscale sorts out how your phone and the Pi find each other, so public IP or not, it just connects. The free plan covers a home setup easily. If you're not sure which of the two you need, I compared them in [Tailscale vs WireGuard for a home lab](https://blog.harshkohli.com/tailscale-vs-wireguard/). Install it on the Pi: ``` curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` Open the link it prints and sign in. Same thing on your phone: get the app, sign in with that same account. Then, in the Tailscale admin console under *DNS*, add your Pi's Tailscale IP (the `100.x.x.x` one, check it with `tailscale ip -4`) as a nameserver and turn on *Override local DNS*. Now your phone uses Pi-hole wherever you are. One extra thing: Pi-hole by default only answers devices on the local network, so in the dashboard go to *Settings → DNS → Interface settings* and set it to *Permit all origins*. That's safe here because you're not forwarding port 53 anywhere; only devices on your tailnet can reach it. If you go the Tailscale route you don't need PiVPN, port forwarding or DuckDNS at all. Honestly, it's less work. ## Step 11: Add your phone to WireGuard with a QR code Back to PiVPN (skip this if you went with Tailscale). Create a profile for each device: ``` pivpn add ``` Name it something obvious, like `phone`. Then show it as a QR code: ``` pivpn -qr phone ``` Install the official WireGuard app on your phone, tap +, choose scan from QR code, and point it at the terminal. Done. On a laptop it's the file in `~/configs/`; copy it over and import it into the WireGuard app. Make one profile per device. If you lose a phone, you can just revoke that one: ``` pivpn remove phone ``` ## Step 12: Test Pi-hole and the VPN on mobile data Turn off Wi-Fi on your phone so you're on mobile data, then switch the VPN on. - On the Pi, `pivpn -c` shows connected clients and when they last did a handshake. - Open the Pi-hole dashboard. Queries from the VPN client (usually something like `10.x.x.x`) should show up. - Open a news site that's normally full of ads. Big difference. - Try opening the Pi-hole admin page by its local IP from your phone. If it loads on mobile data, you're officially home from anywhere. ## Keeping Pi-hole and the Pi updated Once a month or so, SSH in and run: ``` sudo apt update && sudo apt full-upgrade -y pihole -up ``` `pihole -up` updates Pi-hole itself. Gravity (your blocklists) refreshes on its own every week, but you can force it with `pihole -g`. Also worth doing: take a backup. Pi-hole v6 has a Teleporter option under *Settings → Teleporter* that exports everything to one file. Save that file on your PC. SD cards die, it's not if but when, and with the backup you're back up in a few minutes instead of redoing this whole guide. ## Pi-hole and PiVPN troubleshooting **The whole internet stopped working.** The Pi is probably off or its IP changed. Check it's powered and reachable. In an emergency, set the router's DNS back to automatic and everything comes back, then fix the Pi calmly. **Ads still showing on some devices.** Usually the device isn't using Pi-hole. Check for a secondary DNS on the router, "Private DNS" on Android (set it to Off or Automatic), or browsers using their own secure DNS. Chrome and Firefox both have a setting for that. YouTube ads, sadly, come from the same domains as the videos, so Pi-hole can't block them. Nobody has really managed that cleanly. **Some app or site broke.** Go to the Query Log, filter to that phone or laptop, and look at what got blocked right when the app broke. Allowlist that domain and try again. **VPN connects but nothing loads.** Run `pivpn -d`, the built-in debug, and it'll usually point at the problem. Common causes are a wrong endpoint (old IP), the port forward pointing at the wrong IP, or CGNAT. **No handshake at all.** Almost always port forwarding or CGNAT. Double check that the rule is UDP, not TCP. If you're behind CGNAT, go back to the Tailscale section. **Can't log into the dashboard.** Reset the password with `pihole setpassword`. **Pi keeps rebooting randomly.** Power supply, nine times out of ten. Run `vcgencmd get_throttled`; if it's anything other than `throttled=0x0`, get a better adapter. ## FAQ ### Can Pi-hole block YouTube ads? Sadly no. The ads come from the same servers as the videos, so blocking one kills the other. On websites and in most apps Pi-hole does great, but for YouTube it's uBlock Origin in the browser or paying for Premium. ### Does Pi-hole slow down the internet? Not that you'd notice. Lookups for a blocked domain end straight away, and Pi-hole caches the answers it already has, so repeat lookups are often quicker than going out to your ISP's DNS. Download speeds aren't affected at all, because only DNS goes through the Pi. ### Is a Pi Zero 2 W enough, or should I get a Pi 4? For Pi-hole plus WireGuard in a normal home, the Zero 2 W is enough. The Pi 4 is the safer pick if you want wired Gigabit Ethernet without an adapter, or if you think you'll add more stuff later like Home Assistant or a file share. ### How much electricity does it use, and what does it cost? A Pi 4 doing this job pulls roughly 3 to 4 watts. Running all month, that's around 2 to 3 kWh (units). In the US, at roughly $0.15 to $0.17 per kWh, that works out to about 30 to 50 cents a month. In India, at ₹7 to ₹8 per unit, it's about ₹15 to ₹25 a month. A Zero 2 W uses even less. ### Will it work with Starlink, T-Mobile Home Internet, Jio or Airtel? Pi-hole, yes, it doesn't care about your ISP at all since it's all inside your house. The VPN is the tricky bit. Starlink, T-Mobile Home Internet and a lot of Jio and Airtel connections are on CGNAT, and then port forwarding is dead, so you either get a public IP from them or go with [Tailscale](#tailscale-alternative-no-port-forwarding-works-behind-cgnat) instead. ### Is AdGuard Home better than Pi-hole? Both block ads at the DNS level, and for most homes either one is fine. AdGuard Home has encrypted DNS (DoH/DoT) built in and a slightly simpler setup. Pi-hole has a bigger community and more guides around, which helps when something breaks. I'll be doing a proper comparison post soon. I compare them properly in [Pi-hole vs AdGuard Home](https://blog.harshkohli.com/pihole-vs-adguard-home/). ## Wrapping up That's the whole setup. It looks long written out, but most of it is one-time stuff, and after that the Pi just sits there doing its job. If you have a spare Pi lying around in a drawer, this is probably the best use for it. If you get stuck on a step, especially the router bits since every ISP router is different, whether it's an Xfinity gateway or a Jio box, drop a comment and I'll try to help.