Privacy Focused

Download the Site

How to Install Pi-hole on a Raspberry Pi

This guide walks through setting up Pi-hole on a Raspberry Pi to block ads and trackers across your entire home network. Follow these steps carefully.

What You'll Need

Hardware

  • Raspberry Pi (any model—even a Pi Zero works)
  • MicroSD card (8GB minimum, 16GB recommended)
  • SD card to USB adapter (for flashing from your computer)
  • Ethernet cable
  • Power supply for the Raspberry Pi
  • A Mac or Linux machine for the easiest possible setup. Windows can be difficult to work with. If you have a Windows machine, consider using a Linux Live Boot USB to prepare the SD card and ssh connection.

Software

  • Raspberry Pi OS 64-bit Lite - Download from raspberrypi.com/software
  • Balena Etcher - https://etcher.balena.io/ (for flashing the SD card). You can use any other tool that accomplishes the same task. This one is recommended by the Linux Mint team.

Prerequisites

  • Basic command-line knowledge
  • Access to your router's admin panel
  • About 30-45 minutes (or four hours if you're me)

Step 1: Prepare the SD Card

Important: Disconnect from any VPN before starting. VPN connections can interfere with finding devices on your local network. It may also prevent you from accessing the Pi-hole web interface later. Make sure you're on the same local network as your Raspberry Pi.

Flash Raspberry Pi OS

  1. Download Raspberry Pi OS 64-bit Lite from the official website
  2. Download and install Balena Etcher from https://etcher.balena.io/
  3. Insert your SD card into the USB adapter and connect it to your computer
  4. Open Balena Etcher
  5. Select the Raspberry Pi OS image file
  6. Select your SD card as the target
  7. Click "Flash" and wait for the process to complete

Enable SSH Access

After flashing completes, the SD card will remount. You need to enable SSH so you can access the Pi remotely:

  1. Navigate to the boot partition of the SD card (it should be visible in your file manager)
    • Sometimes this doesn't work right on Windows. You may need to use a mac or figure out a way to load linux temporarily on your computer using a Live Boot USB Drive. If you have a Linux machine, you can use that to prepare the SD card.
  2. Create a blank file named ssh (no file extension)
  • On Linux/Mac: touch ssh in the boot directory
  • On Windows: Create a new text file and remove the .txt extension entirely

Set Up Default User Credentials

Create a file named userconf.txt in the boot partition:

  1. Open a terminal on your Mac or Linux machine (or use a terminal emulator on Windows)
    • If you don't have a terminal, you can probably generate an openssl password online, but be cautious about using online tools for password generation. If you do use an online tool, make sure it's reputable and secure. It's generally safer to generate the password hash locally on your machine.
  2. Generate a password hash by running:
    echo 'yourpassword' | openssl passwd -6 -stdin
    Replace yourpassword with your actual desired password
  3. Copy the hash that's output (it will look like $6$random_characters...)
  4. Create userconf.txt in the boot partition
  5. Add this line to the file:
    pi:THE_HASH_YOU_GENERATED
    Replace THE_HASH_YOU_GENERATED with the hash from step 2

Save the file. Your Pi will now boot with username pi and the password you set.

Step 2: Boot and Connect the Raspberry Pi

  1. Eject the SD card from your computer
  2. Insert the SD card into your Raspberry Pi
  3. Connect the Raspberry Pi to your router using the ethernet cable
  4. Plug in the power supply to boot the Pi
  5. Wait about 5 minutes for the initial boot and setup to complete. The light will be flashing while it sets up for the first time. This is a good time to go grab something tasty to drink.

The Pi needs time to expand the filesystem and complete first-boot configuration. Don't rush this step.

Step 3: Find Your Raspberry Pi on the Network

You need to find the Pi's IP address to connect to it.

Option 1: Using Hostname (Easiest)

On Linux or Mac, try:

ping raspberrypi.local

If this works, you'll see responses. Press Ctrl+C to stop. The IP address will be shown in the output.

Option 2: Using nmap (If hostname doesn't work)

WARNING: nmap is a powerful network scanning tool. Use it responsibly and only on networks you own or have permission to scan. You are NOT allowed to use this on public networks or networks you don't have explicit permission to scan. Unauthorized scanning can be illegal and may lead to consequences.

If raspberrypi.local doesn't resolve, use nmap to scan your network:

Install nmap:

  • Linux: sudo apt install nmap
  • Mac/Windows: Download from https://nmap.org/download.html

Find your network range:

ip a

Look for your active network connection (usually starts with 192.168.x.x or 10.0.x.x). Note the subnet. For example, if your computer's IP is 192.168.50.100, your subnet is likely 192.168.50.0/24.

Scan for the Raspberry Pi:

sudo nmap -sn 192.168.50.0/24

Replace 192.168.50.0/24 with your actual subnet.

Look for a result like:

Nmap scan report for raspberrypi (192.168.50.227)
Host is up (0.00050s latency).

Write down the IP address. You'll need it for SSH and router configuration. In this example, it's 192.168.50.227.

Step 4: Connect via SSH

Open a terminal and connect to your Pi:

ssh pi@192.168.50.227

Replace 192.168.50.227 with your Pi's actual IP address.

When prompted:

  • Type yes to accept the fingerprint (first connection only)
  • Enter the password you set earlier

You should now be logged into your Raspberry Pi's command line.

Step 5: Update the Raspberry Pi

Before installing anything, update the system:

sudo apt update && sudo apt upgrade -y

This may take several minutes depending on how many packages need updating. Let it complete.

Step 6: Install Pi-hole

Pi-hole provides a one-step automated installer. Get the latest command from their GitHub page: https://github.com/pi-hole/pi-hole/#one-step-automated-install

Use their curl command shown in github.

Note: Always verify this command on Pi-hole's official GitHub before running it. Install scripts should always be checked against official sources.

During Installation

The installer will guide you through setup:

  1. Press Enter to begin
  2. Choose your network interface (select the ethernet interface)
  3. Select your upstream DNS provider (Cloudflare, Google, OpenDNS, etc.)
  4. Use recommended blocklists (yes)
  5. Install the web admin interface (yes)
  6. Install lighttpd web server (yes)
  7. Enable query logging (your choice—yes for visibility, no for privacy)
  8. Set privacy mode (choose your preference)

Important: At the end, the installer will display:

  • The web interface address (e.g., http://192.168.50.227/admin or http://pi.hole:80/admin)
  • Your admin password

Write down the admin password. You'll need it to access the web interface. This is different than your raspbery pi password. Make sure to keep both passwords safe and secure.

If you miss it, you can reset the password later with:

pihole -a -p

Step 7: Configure Your Router

Now configure your router to use Pi-hole as the DNS server for all devices.

Access Router Settings

  1. Open a web browser
  2. Navigate to your router's admin panel (commonly 192.168.1.1, 192.168.0.1, or 10.0.0.1)
  3. Log in with your router's admin credentials
  4. Make sure to update your router's firmware if it has been a while since you've last checked it. This is important for security and performance.

Update DNS Settings

The exact location varies by router, but look for:

  • DHCP settings
  • LAN settings
  • DNS settings
  • Network settings

You need to find where DNS servers are configured.

Set both DNS servers to your Pi-hole's IP address:

  • Primary DNS: 192.168.50.227 (your Pi's IP)
  • Secondary DNS: 192.168.50.227 (same IP)

Why set both to the same address? If you put a different secondary DNS (like Google's 8.8.8.8), devices will use it when Pi-hole is slow or unreachable, bypassing your blocking. Setting both to Pi-hole ensures all DNS traffic goes through it.

Save and Reboot

  1. Save the DNS settings
  2. Reboot your router if prompted
  3. Devices may need to reconnect to wifi or renew their DHCP leases

To force immediate updates, you can:

  • Disconnect and reconnect to wifi on each device
  • Reboot devices
  • Wait for DHCP leases to naturally renew (usually 24 hours)

Step 8: Verify It's Working

Check the Web Interface

  1. Open a browser
  2. Go to http://YOUR_PI_IP_ADDRESS/admin or http://pi.hole:80/admin
  3. Log in with the password from installation
  4. You should see the Pi-hole dashboard with query statistics

Test Blocking

Visit a site known for heavy ads (news sites work well). Ads should be blocked. Check the Pi-hole dashboard to see blocked queries increasing.

Check DNS on Your Devices

On a device, check its DNS settings:

  • It should show your Pi-hole's IP as the DNS server
  • If it shows your router's IP, that's fine—the router forwards to Pi-hole

Maintenance

Pi-hole requires minimal maintenance, but stay on top of updates.

Update Pi-hole Monthly

About once a month, SSH into your Pi and run:

pihole -up

This updates Pi-hole software and blocklists.

Update Raspberry Pi OS

Periodically update the underlying OS:

sudo apt update && sudo apt upgrade -y

Monitor Performance

Check the web dashboard occasionally to ensure:

  • Queries are being processed
  • Blocklists are up to date
  • The Pi isn't overloaded (unlikely on home networks)

Troubleshooting

DNS not working after setup:

  • Verify router DNS settings are saved
  • Check that Pi-hole service is running: pihole status
  • Restart Pi-hole: pihole restartdns

Some devices bypass Pi-hole:

  • Some devices (smart TVs, IoT gadgets) have hardcoded DNS
  • Configure your router to block outbound DNS requests on port 53 except from Pi-hole
  • Or use firewall rules to force all DNS through Pi-hole

Sites breaking due to over-blocking:

  • Use the web interface to whitelist specific domains
  • Adjust blocklist aggressiveness
  • Check query logs to see what's being blocked

Pi-hole becomes unreachable:

  • Ensure the Pi has a static IP or DHCP reservation
  • Check network cables and power
  • Access the Pi physically if SSH fails

Next Steps

Now that Pi-hole is running:

  • Add additional blocklists through the web interface
  • Configure whitelists for sites that break
  • Review query logs to understand what your devices contact

Additional Resources

  • Official Pi-hole documentation: https://docs.pi-hole.net/
  • Pi-hole community forum: https://discourse.pi-hole.net/
  • Recommended blocklists: Search "pi-hole blocklists" for curated collections
  • Advanced configuration: Look into Pi-hole's gravity database and custom DNS records

Resources for block lists

These are some of the most popular and effective block lists for Pi-hole. You can add them through the web interface under "Group Management" > "Adlists". Always review block lists before adding them to ensure they align with your blocking goals. They will massively increase the number of blocked domains, which can improve privacy but may also cause some sites to break. Start with a few and test your browsing experience before adding more.

  • https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  • https://big.oisd.nl/
  • Apple Tracker: https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/domains/native.apple.txt
  • https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/adblock/pro.txt
  • Gambling: https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/adblock/gambling.txt
  • LG: https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/domains/native.lgwebos.txt
  • TikTok Fingerprint Block: https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/domains/native.tiktok.extended.txt
  • Samsung List 1: https://raw.githubusercontent.com/RPiList/specials/refs/heads/master/Blocklisten/samsung
  • Samsung List 2: https://gist.githubusercontent.com/wassname/b594c63222f9e4c83ea23c818440901b/raw/1b0afd2aecf3a099f1681b1cf18fc0e6e2fa116a/Samsung%2520Smart-TV%2520Blocklist%2520Adlist%2520(for%2520PiHole)
  • Samsung List 3: https://raw.githubusercontent.com/hagezi/dns-blocklists/refs/heads/main/domains/native.samsung.txt

Network-level blocking takes effort to set up, but once running, it protects every device automatically.