# Pi Hole Ad Blocker with Pi Zero W

## Overview

Danger: There are reports that this guide does not work with PiHole version 6 and later. If you are using version 6.x and later, please look to other sources for setup. We have no expected ETA for updating this guide.

![](https://cdn-learn.adafruit.com/assets/assets/000/045/338/medium800/raspberry_pi_pihole.gif?1502854586)

A long time ago we made a Pi into a WiFi gateway that also blocked ads but the Pi Hole project does a _way_ better job!

This project will make your Pi Zero W act as a DNS ( **Domain Name Server** ) The kind of device that tells you that **adafruit.com** is known as IP address 104.20.38.240.

Except Pi Hole DNS will do a special trick, when it is asked for the IP address of ads.adserver.com (for example) it will return nothing! So you will never even connect to the ad server and get the ad. Your connection will be faster, less data, and no intrusive ads. It works great on computers, tablets, phones, etc. Even if you cannot run an ad-blocker plugin on your phone or tablet, this will work and ad-blocker-detectors can't tell you're running it.

Unlike our WiFi gateway demo, you do not have to set up the Pi as your access point, you will only use it as a DNS ad blocker so it will not act as a bottleneck

![](https://cdn-learn.adafruit.com/assets/assets/000/045/337/medium800thumb/raspberry_pi_adfade.jpg?1502854412)

We upgraded our Pi Zero Pi Hole with a little display, that makes setting up clients easy and also gives you some nifty stats!

Follow along with this guide to DIY your own

# Pi Hole Ad Blocker with Pi Zero W

## Project Parts

This project can be done with any Raspberry Pi, but for the most adorably compact version we're using a Pi Zero W - this has enough power to do what we want, and has built in WiFi too!

# Pi Zero W base parts

Its easiest if you pick up a Pi Zero W budget pack as it contains most everything you need

### Raspberry Pi Zero W Budget Pack - Includes Pi Zero W

[Raspberry Pi Zero W Budget Pack - Includes Pi Zero W](https://www.adafruit.com/product/3410)
Remember those cereal commercials that would always say, "part of a complete breakfast"? Well the Pi Zero's a lot like that bowl of cereal - while it's great on its own, you need a lot of accessories to make it a complete meal.

The **Pi Zero W...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/3410)
[Related Guides to the Product](https://learn.adafruit.com/products/3410/guides)
![Raspberry Pi Zero, micro SD card, cables, headers and case](https://cdn-shop.adafruit.com/640x480/3410-02.jpg)

But you can also just DIY with the minimum requirements:

### Part: Pi Zero W
quantity: 1
the type of low cost game-changing product Raspberry Pi's known for - the super light, super lean microcomputer we've come to know and low, but now with built-in WiFi.
[Pi Zero W](https://www.adafruit.com/product/3400)

### Part: 4G or larger SD Card
quantity: 1
You will be burning this card with Raspbian Jessie Lite so its ok if its blank or pre-burned
[4G or larger SD Card](https://www.adafruit.com/product/102)

### Part: Adafruit Pi Zero Enclosure
quantity: 1
Adafruit's classic, sturdy plastic enclosure. Keeps your Pi Zero safe and sleek.
[Adafruit Pi Zero Enclosure](https://www.adafruit.com/product/3252)

### Part: 5V 1A USB wall adapter
quantity: 1
This one is plenty good and you can use any Micro USB cable with it
[5V 1A USB wall adapter](https://www.adafruit.com/product/501)

### Part: 5V 2.4A USB wall adapter
quantity: 1
Super powerful for any uses, and comes with a built in MicroUSB cable
[5V 2.4A USB wall adapter](https://www.adafruit.com/product/1995)

# Pi OLED Display Addition

If you want to add an OLED display (which is suggested!) you'll also need:

### Adafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry Pi

[Adafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry Pi](https://www.adafruit.com/product/3527)
If you're looking for the most compact li'l display for a [Raspberry Pi](https://www.adafruit.com/category/361) (most likely a [Pi Zero](https://www.adafruit.com/category/813)) project, this might be just the thing you need!

The **Adafruit...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/3527)
[Related Guides to the Product](https://learn.adafruit.com/products/3527/guides)
![Top view of assembled and powered on Adafruit PiOLED - 128x32 Monochrome OLED on a Pi Zero. The OLED displays a data readout.](https://cdn-shop.adafruit.com/640x480/3527-04.jpg)

 **If you are using a Pi Zero W you'll need to add 2x20 headers too **

### Part: 2x20 Male Header
quantity: 1
Solder this in to plug in Pi HATs, GPIO cables, etc as you would into a normal Pi. Requires soldering
[2x20 Male Header](https://www.adafruit.com/product/2822)

 **or**

### Part: 2x20 No-Solder Hammer Headers
quantity: 1
If your soldering isn't quite up to scratch, or you just don't own a soldering iron yet, then these nifty hammer headers from Pimoroni might be just what you need. 
[2x20 No-Solder Hammer Headers](https://www.adafruit.com/product/3413)

# Other things you may need...

You also need a way to burn that SD card!

# Using a Pi 3 Instead of Pi Zero W

Instead of a Pi Zero W you can directly substitute in a Pi 3 or 4 which also has built in WiFi, you won't need the 2x20 header in that case

### Part: Raspberry Pi 3
quantity: 1
Raspberry Pi 3 with WiFi built in!
[Raspberry Pi 3](https://www.adafruit.com/product/3055)

# Pi Hole Ad Blocker with Pi Zero W

## Prepare the Pi

![](https://cdn-learn.adafruit.com/assets/assets/000/045/314/medium800/raspberry_pi_banner.jpg?1502841856)

The Pi Zero W is a very minimal computer, so it requires a little work to get it up and running.

We have a guide on how to set up your Pi Zero W 'headless' which is how we recommend you get started. Check out the guide for how to do that!

[Set up your Pi Zero W](https://learn.adafruit.com/raspberry-pi-zero-creation/)
Here's the quick-start for people with some experience:

1. Download the [Raspberry Pi Imager](https://www.raspberrypi.com/software/) to your computer
2. Install the 64-bit Lite Raspberry Pi to your micro SD card using the imager. you may need to go to **Raspberry Pi OS (other)** to find it.
3. When it asks you about settings, be sure you have your network settings entered and SSH enabled under Services.
4. [Re-plug the SD card into your computer (don't use your Pi yet!) and set up your wifi connection by editing supplicant.conf](../../../../raspberry-pi-zero-creation/text-file-editing)
5. Plug the SD card into the Pi Zero W
6. If you have an HDMI monitor we recommend connecting it up via the mini HDMI adapter we provide in the budget pack - so you can see that it's booting OK
7. Plug in power to the Pi Zero W - you will see the green LED flicker a little. The Pi Zero will reboot while it sets up so wait a good 10 minutes
8. [If you are running Windows on your computer, install Bonjour support so you can use **.local** names, you'll need to reboot Windows after installation](../../../../bonjour-zeroconf-networking-for-windows-and-linux#microsoft-windows)
9. [You can then **ssh** into **raspberrypi.local**](../../../../adafruits-raspberry-pi-lesson-6-using-ssh) or whichever hostname you entered under settings.

# Pi Hole Ad Blocker with Pi Zero W

## Install Pi Hole

Use the following instructions to install Pi Hole:

[https://github.com/pi-hole/pi-hole/#one-step-automated-install](https://github.com/pi-hole/pi-hole/#one-step-automated-install)

# Pre-Check

OK once you have set your Pi up and the WiFi is connecting to your home or office network, and you can `ssh` into it, continue with these easy steps! If you cannot connect via `ssh` yet, go back and read some of our guides until  you are able to log into your Pi.

![](https://cdn-learn.adafruit.com/assets/assets/000/045/316/medium800/raspberry_pi_ssh.png?1502845158)

# Change Hostname

I like to do this first so I don't get confused between all the different Pi's in the house.

The hostname can be set in the imager before you get started, but if you forgot or you'd like to change it afterwards, just edit the hostname with  **sudo nano /etc/hostname** and put something else on that first line, like **pi-hole**

![](https://cdn-learn.adafruit.com/assets/assets/000/045/317/medium800/raspberry_pi_hostname.png?1502845247)

Also change it in the hosts file with **sudo nano /etc/hosts** to match the same name. It's probably the last line:

![](https://cdn-learn.adafruit.com/assets/assets/000/073/755/medium800/adafruit_products_Screenshot_from_2019-03-27_16-09-58.png?1553728471)

Reboot and when you ssh in again, use **pi-hole.local**

Now's also a good time to change the Pi's password with **passwd**

# Run Pi Hole Installer

There's more information on how installation at [https://pi-hole.net/](https://pi-hole.net/) - as of the writing of this guide, its easier to just run:

```auto
curl -sSL https://install.pi-hole.net | bash
```

It will take quite a while to install, and may seem to 'hang' at points. Just let it do its thing for about 20 minutes!

Danger: The screenshots below are based on the 5.18.2 release of Pi-Hole. The latest version may have slightly different screens and options, but generally accepting defaults to everything should be OK.

![](https://cdn-learn.adafruit.com/assets/assets/000/129/282/medium800/adafruit_products_Screenshot_2024-04-09_at_2.17.05_PM.png?1712700509)

![](https://cdn-learn.adafruit.com/assets/assets/000/129/283/medium800/adafruit_products_Screenshot_2024-04-09_at_2.13.14_PM.png?1712700542)

# Configuration
The installer may complain about needing a requiring IP address, which is recommended. This is because DHCP reservations can expire. However, in practice, if the pi stays in communication with your DHCP server, it usually just keeps renewing the same IP address, which works well enough. if you have an advanced network set up, you can configure a custom IP address

![adafruit_products_Screenshot_2024-04-09_at_2.17.37_PM.png](https://cdn-learn.adafruit.com/assets/assets/000/129/284/medium640/adafruit_products_Screenshot_2024-04-09_at_2.17.37_PM.png?1712700635)

If you have your pi has multiple network interfaces such as WiFi and an ethernet adapter, it will ask you which one you would like to use.

![adafruit_products_Screenshot_2024-04-09_at_2.18.00_PM.png](https://cdn-learn.adafruit.com/assets/assets/000/129/285/medium640/adafruit_products_Screenshot_2024-04-09_at_2.18.00_PM.png?1712700942)

Pick who will be the upstream DNS (for non-ad blocked sites) - Google is fine and will probably be up all the time

![adafruit_products_Screenshot_2024-04-09_at_2.18.18_PM.png](https://cdn-learn.adafruit.com/assets/assets/000/129/286/medium640/adafruit_products_Screenshot_2024-04-09_at_2.18.18_PM.png?1712701063)

You can add any additional third party lists here or you can just use the default.

![adafruit_products_Screenshot_2024-04-09_at_2.18.31_PM.png](https://cdn-learn.adafruit.com/assets/assets/000/129/287/medium640/adafruit_products_Screenshot_2024-04-09_at_2.18.31_PM.png?1712701140)

The Web Interface is kinda cool, and is password protected. We'll be showing most of the stats on the little OLED but we still need the API to be running so install this.

You'll also need a web interface running, so select this as well unless you already have another one installed.

![adafruit_products_Screenshot_2024-04-09_at_2.18.47_PM.png](https://cdn-learn.adafruit.com/assets/assets/000/129/288/medium640/adafruit_products_Screenshot_2024-04-09_at_2.18.47_PM.png?1712701216)

![adafruit_products_Screenshot_2024-04-09_at_2.18.56_PM.png](https://cdn-learn.adafruit.com/assets/assets/000/129/289/medium640/adafruit_products_Screenshot_2024-04-09_at_2.18.56_PM.png?1712701297)

If you'd like to retain a log of the ads that are blocked, you can enable query logging. If you enable it, you'll also be asked about the amount of content that you'd like logged.

![adafruit_products_Screenshot_2024-04-09_at_2.19.03_PM.png](https://cdn-learn.adafruit.com/assets/assets/000/129/290/medium640/adafruit_products_Screenshot_2024-04-09_at_2.19.03_PM.png?1712701363)

![adafruit_products_Screenshot_2024-04-09_at_2.19.25_PM.png](https://cdn-learn.adafruit.com/assets/assets/000/129/291/medium640/adafruit_products_Screenshot_2024-04-09_at_2.19.25_PM.png?1712701449)

It will keep installing! Just hold tight...

![](https://cdn-learn.adafruit.com/assets/assets/000/129/296/medium800/adafruit_products_Screenshot_2024-04-09_at_3.06.35_PM.png?1712701743)

When its done you'll get this final config screen! Copy & paste the password into another window for now

![](https://cdn-learn.adafruit.com/assets/assets/000/129/294/medium800/adafruit_products_Screenshot_2024-04-09_at_3.02.47_PM.png?1712701699)

# Test Admin Page

On your desktop computer or tablet, visit [http://pi.hole/admin](http://pi.hole/admin) or if that doesn't work, try [http://[your-ip]/admin](http:/127.0.0.1/admin) (replacing [your-ip] with you IP address) and you should see an administration panel!

![](https://cdn-learn.adafruit.com/assets/assets/000/045/327/medium800/raspberry_pi_admin.png?1502846397)

# Test Blocking
On your tablet, phone, computer, etc - Set up your **DNS** server in the network settings to be the IP address of the Pi

![](https://cdn-learn.adafruit.com/assets/assets/000/045/341/medium800/raspberry_pi_djs.png?1502855696)

You _may_ need to restart your network or browser to have it kick in, also there may be some cached ads so don't worry if not everything is blocked. Visit your favorite site with ads (not adafruit.com cuz we don't have any! :) and see the difference!

![](https://cdn-learn.adafruit.com/assets/assets/000/045/342/medium800thumb/raspberry_pi_adfade.jpg?1502855755)

Now that you've got that done, lets continue and install the display!

# Pi Hole Ad Blocker with Pi Zero W

## Install PiOLED

Our little PiOLED add on makes a very cute and easy way to display the Pi Hole stats. We were inspired to add this when we saw this tweet!

![](https://cdn-learn.adafruit.com/assets/assets/000/045/329/medium800/raspberry_pi_twet.png?1502846588)

What a perfect use! Here's how to add it on for some nice stats. It also displays the hostname and IP address so if you forget it you can just look at the display. It will also tick up when its in use so you can tell its working.

# Install 2x20 Header

If you are using a Pi Zero you'll need to solder in or somehow attach a 2x20 header so you can plug in the Pi OLED. Use either a plain 2x20 header and [solder it in using an iron + some solder...](../../../../adafruit-guide-excellent-soldering)

### Break-away 0.1" 2x20-pin Strip Dual Male Header

[Break-away 0.1" 2x20-pin Strip Dual Male Header](https://www.adafruit.com/product/2822)
If we could eat headers, we'd have them for breakfast, lunch, and dinner.  But we can't :( So we're making the best of it and selling them!

This **2x20-pin strip male header** is a great way to add pins to 2x20 0.1" holes in a PCB....

In Stock
[Buy Now](https://www.adafruit.com/product/2822)
[Related Guides to the Product](https://learn.adafruit.com/products/2822/guides)
![Angled shot of a 0.1" 2x20-pin dual plug header strip.](https://cdn-shop.adafruit.com/640x480/2822-00.jpg)

Or you can use Hammer headers which do not need soldering!

### GPIO Hammer Headers - Solderless Raspberry Pi Connectors

[GPIO Hammer Headers - Solderless Raspberry Pi Connectors](https://www.adafruit.com/product/3413)
If your soldering isn't quite up to scratch, or you just don't own a soldering iron yet, then these nifty **hammer headers**  from [Pimoroni](https://shop.pimoroni.com/) might be just what you need. They come in both male and female, and use crafty...

In Stock
[Buy Now](https://www.adafruit.com/product/3413)
[Related Guides to the Product](https://learn.adafruit.com/products/3413/guides)
![GPIO Hammer Header kit - Solderless Raspberry Pi Connectors with installation hardware](https://cdn-shop.adafruit.com/640x480/3413-01.jpg)

Either way, you'll want to end up with something like this:

![](https://cdn-learn.adafruit.com/assets/assets/000/045/339/medium800/raspberry_pi_2822-03.jpg?1502855250)

# Setup Virtual Environment with Blinka

Starting with the Bookworm version of Raspberry Pi OS, you will need to install your python modules in a virtual environment. Even on earlier versions, it's still recommended to install a virtual environment. You can find more information in the [Python Virtual Environment Usage on Raspberry Pi](https://learn.adafruit.com/python-virtual-environment-usage-on-raspberry-pi) guide. To Install and activate the virtual environment, use the following commands:

```terminal
sudo apt install python3-venv
sudo apt-get install -y python3-pip
python3 -m venv pihole --system-site-packages
source pihole/bin/activate
pip3 install --upgrade adafruit-python-shell
wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/raspi-blinka.py
sudo -E env PATH=$PATH python3 raspi-blinka.py
```

You will need to activate the virtual environment every time the Pi is rebooted. To activate it:

```terminal
source pihole/bin/activate
```

To deactivate, you can use `deactivate`, but leave it active for now.

## Python Setup
This guide assumes that you've gotten your Raspberry Pi up and running, have CircuitPython installed, and have installed CircuitPython libraries for the PiOLED. 

```terminal
source pihole/bin/activate
pip3 install adafruit-circuitpython-ssd1306
sudo apt-get install python3-pil
```

![](https://cdn-learn.adafruit.com/assets/assets/000/045/331/medium800/raspberry_pi_3527_top_demo_ORIG.jpg?1502846774)

A nice font really helps with this little OLED display, something other than the default PIL font. First thing I did is update the font so its a little clearer. [I used Kottke's free Silkscreen font which looks great on small screens.](http://kottke.org/plus/type/silkscreen/)

It's easy to install on your Pi, run

```terminal
cd ~
wget http://kottke.org/plus/type/silkscreen/download/silkscreen.zip
unzip silkscreen.zip
```

![](https://cdn-learn.adafruit.com/assets/assets/000/073/765/medium800/adafruit_products_Screenshot_from_2019-03-28_10-16-08.png?1553793379)

# Update stats.py program

Here's the new stats.py code which uses the PiOLED.

Create a new file with **nano ~pi/stats.py** and paste this code below in! Then save it.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Pi_Hole_Ad_Blocker/stats.py

Warning: 

You'll notice its very similar to the original **stats.py** but we've added PiHole API support. Here's how we did that!

First up, Pi Hole stats are available through the web server, in json format, so we need to add web requests and json parsing to python. Then set the URL for the API access, which is localhost (the same computer) and through the admin page:

```auto
import subprocess
import json
import requests

api_url = 'http://localhost/api/stats/summary'
```

We load up the nice Silkscreen font here, in 8 point type. Note that we have to have the full path of the file.

```auto
# Load nice silkscreen font
font = ImageFont.truetype("/home/pi/slkscr.ttf", 8)
```

This is where we grab the API data. I put it in a **try** block, so it would retry in case the API access failed for some reason

```auto
# Pi Hole data!
    try:
        r = requests.get(api_url, timeout=2)
        r.raise_for_status()
        data = r.json()
        DNSQUERIES = data["queries"]["total"]
        ADSBLOCKED = data["queries"]["blocked"]
        CLIENTS    = data["clients"]["total"]
    except (KeyError, requests.RequestException):
        DNSQUERIES = 0
        ADSBLOCKED = 0
        CLIENTS    = 0
```

If you want to print out different info, run this small script in python to see what is available:

```auto
import json
import requests

api_url = 'http://localhost/api/stats/summary'
r = requests.get(api_url)
data = json.loads(r.text)
print(data)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/073/762/medium800/adafruit_products_Screenshot_from_2019-03-28_10-11-21.png?1553793224)

You can also customize the display printout, but i liked having the IP first, then the pi hole stats below:

```auto
    draw.text((x, top),       "IP: " + str(IP) + "( " + HOST + ")",  font=font, fill=255)
    draw.text((x, top+8),     "Ads Blocked: " + str(ADSBLOCKED), font=font, fill=255)
    draw.text((x, top+16),    "Clients:     " + str(CLIENTS),  font=font, fill=255)
    draw.text((x, top+24),    "DNS Queries: " + str(DNSQUERIES),  font=font, fill=255)
```

## Disable API Authentication
This step is critical to being able to access the Pi Hole API. Press enter (leave blank) when prompted for API password.

```terminal
sudo pihole setpassword
```

# Test & Stats at Startup

Once you have the script saved, you can run it with:

```terminal
python3 ./stats.py
```

and look on the OLED to make sure you see your IP address and such!

Lastly we just want to make this run at boot. We'll do that the easy way by editing /etc/rc.local with **sudo nano /etc/rc.local** and adding **sudo ~pi/pihole/bin/python3 ~pi/stats.py &** before **exit 0**

![](https://cdn-learn.adafruit.com/assets/assets/000/129/298/medium800/adafruit_products_Screenshot_2024-04-09_at_5.04.09_PM.png?1712707470)

Then save and you can reboot to test it out

![](https://cdn-learn.adafruit.com/assets/assets/000/045/340/medium800/raspberry_pi_close.gif?1502855304)

# Pi Hole Ad Blocker with Pi Zero W

## Install Mini PiTFT

We've updated our popular PiOLED script for use with the [Mini PiTFT](https://www.adafruit.com/product/4393), a 135x240 Color TFT add-on for your Raspberry Pi. This cute little display has _two_ tactile buttons on GPIO pins that we'll use to make a simple user-interface display for your Pi-Hole.

### Adafruit Mini PiTFT - 135x240 Color TFT Add-on for Raspberry Pi

[Adafruit Mini PiTFT - 135x240 Color TFT Add-on for Raspberry Pi](https://www.adafruit.com/product/4393)
If you're looking for the most compact li'l color display for a [Raspberry Pi](https://www.adafruit.com/category/361) (most likely a [Pi Zero](https://www.adafruit.com/category/813)) project, this might be just the thing you need!

The **...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/4393)
[Related Guides to the Product](https://learn.adafruit.com/products/4393/guides)
![Video of Adafruit Mini PiTFT - 135x240 Color TFT Add-on assembled onto a Raspberry Pi 3. The TFT displays a bootup.](https://cdn-shop.adafruit.com/product-videos/640x480/4393-03.jpg)

## Install 2x20 Header

If you are using a Pi Zero, you'll need to solder on or somehow attach a 2x20 header so you can plug in the Pi OLED. Use either a plain 2x20 header and [solder it in using an iron + some solder...](../../../../adafruit-guide-excellent-soldering)

### Break-away 0.1" 2x20-pin Strip Dual Male Header

[Break-away 0.1" 2x20-pin Strip Dual Male Header](https://www.adafruit.com/product/2822)
If we could eat headers, we'd have them for breakfast, lunch, and dinner.  But we can't :( So we're making the best of it and selling them!

This **2x20-pin strip male header** is a great way to add pins to 2x20 0.1" holes in a PCB....

In Stock
[Buy Now](https://www.adafruit.com/product/2822)
[Related Guides to the Product](https://learn.adafruit.com/products/2822/guides)
![Angled shot of a 0.1" 2x20-pin dual plug header strip.](https://cdn-shop.adafruit.com/640x480/2822-00.jpg)

Or you can use Hammer headers which do not need soldering.

### GPIO Hammer Headers - Solderless Raspberry Pi Connectors

[GPIO Hammer Headers - Solderless Raspberry Pi Connectors](https://www.adafruit.com/product/3413)
If your soldering isn't quite up to scratch, or you just don't own a soldering iron yet, then these nifty **hammer headers**  from [Pimoroni](https://shop.pimoroni.com/) might be just what you need. They come in both male and female, and use crafty...

In Stock
[Buy Now](https://www.adafruit.com/product/3413)
[Related Guides to the Product](https://learn.adafruit.com/products/3413/guides)
![GPIO Hammer Header kit - Solderless Raspberry Pi Connectors with installation hardware](https://cdn-shop.adafruit.com/640x480/3413-01.jpg)

Either way, you'll want to end up with something like this:

![](https://cdn-learn.adafruit.com/assets/assets/000/085/745/medium800/adafruit_products_raspberry_pi_2822-03.jpg?1576167134)

# Setup Virtual Environment with Blinka

Starting with the Bookworm version of Raspberry Pi OS, you will need to install your python modules in a virtual environment. Even on earlier versions, it's still recommended to install a virtual environment. You can find more information in the [Python Virtual Environment Usage on Raspberry Pi](https://learn.adafruit.com/python-virtual-environment-usage-on-raspberry-pi) guide. To Install and activate the virtual environment, use the following commands:

```auto
sudo apt install python3-venv
sudo apt-get install -y python3-pip
python3 -m venv pihole --system-site-packages
source pihole/bin/activate
pip3 install --upgrade adafruit-python-shell
wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/raspi-blinka.py
sudo -E env PATH=$PATH python3 raspi-blinka.py
```

You will need to activate the virtual environment every time the Pi is rebooted. To activate it:

```terminal
source pihole/bin/activate
```

To deactivate, you can use `deactivate`, but leave it active for now.

## Python Setup

This guide assumes that you've gotten your Raspberry Pi up and running, have CircuitPython installed, and have installed CircuitPython libraries for the Mini PiTFT. If not, follow the steps in the guide below and come back to this page when you've completed them.

```auto
source pihole/bin/activate
pip3 install adafruit-circuitpython-rgb-display
sudo apt-get install fonts-dejavu python3-pil python3-numpy
```

## Update the stats.py program

Here's the new **stats.py** code which uses the Mini PiTFT. 

**Create a new**  **file** using nano `~pi/stats.py` and **paste the code** below in. Then, **save the code**.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Pi_Hole_Ad_Blocker/mini_pitft_stats.py

You'll notice it's very similar to the original **stats.py** , but we've added PiHole API support. Here's how we did that:

First up, Pi Hole stats are available through the web server, in JSON format, so we need to add web requests and JSON parsing to Python. Then set the URL for the API access, which is localhost (the same computer) and through the admin page:

```python
# Import Python System Libraries
import time
import json
import subprocess

# Import Requests Library
import requests

api_url = 'http://localhost/api/stats/summary'
```

We load up the nice DejaVuSans font here. Note that we have to have the full path of the file.

```python
# Alternatively load a TTF font.  Make sure the .ttf font file is in the
# same directory as the python script!
# Some other nice fonts to try: http://www.dafont.com/bitmap.php
FONT_PATH = "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
font = ImageFont.truetype(FONT_PATH, 20)
```

This is where we grab the API data. I put it in a  **try**  block, so it would retry in case the API access failed for some reason

```python
# Pi Hole data!
    try:
        r = requests.get(api_url)
        data = json.loads(r.text)
        DNSQUERIES = data['dns_queries_today']
        ADSBLOCKED = data['ads_blocked_today']
        CLIENTS = data['unique_clients']
    except KeyError:
        time.sleep(1)
        continue
```

If you want to print out different info, run this small script in python to see what is available:

```python
import json
import requests

api_url = 'http://localhost/api/stats/summary'
r = requests.get(api_url)
data = json.loads(r.text)
print(data)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/085/746/medium800/adafruit_products_Screenshot_from_2019-03-28_10-11-21.png?1576169223)

Since the MiniTFT has _two_ tactile push-buttons, we modified the script to print out extra information from the Raspberry Pi when you press the top button.

```python
if not buttonA.value:  # just button A pressed
        draw.text((x, y), IP, font=font, fill="#FFFF00")
        y += font.getsize(IP)[1]
        draw.text((x, y), CPU, font=font, fill="#FFFF00")
        y += font.getsize(CPU)[1]
        draw.text((x, y), MemUsage, font=font, fill="#00FF00")
        y += font.getsize(MemUsage)[1]
        draw.text((x, y), Disk, font=font, fill="#0000FF")
        y += font.getsize(Disk)[1]
        draw.text((x, y), "DNS Queries: {}".format(DNSQUERIES), font=font, fill="#FF00FF")
    else:
        draw.text((x, y), IP, font=font, fill="#FFFF00")
        y += font.getsize(IP)[1]
        draw.text((x, y), HOST, font=font, fill="#FFFF00")
        y += font.getsize(HOST)[1]
        draw.text((x, y), "Ads Blocked: {}".format(str(ADSBLOCKED)), font=font, fill="#00FF00")
        y += font.getsize(str(ADSBLOCKED))[1]
        draw.text((x, y), "Clients: {}".format(str(CLIENTS)), font=font, fill="#0000FF")
        y += font.getsize(str(CLIENTS))[1]
        draw.text((x, y), "DNS Queries: {}".format(str(DNSQUERIES)), font=font, fill="#FF00FF")
        y += font.getsize(str(DNSQUERIES))[1]
```

## Disable API Authentication
This step is critical to being able to access the Pi Hole API. Press enter (leave blank) when prompted for API password.

```terminal
sudo pihole setpassword
```

## Test & Stats at Startup
Once you have the script saved, you can run it with

```terminal
python3 stats.py
```

Look on the Mini PiTFT to make sure you see your IP address along with some statistics from Pi-Hole.

**Pushing the top button should display _extra_ statistics about the Pi** such as its hostname, CPU load, memory utilization, disk usage, and DNS queries.

![adafruit_products_IMG_8407.jpg](https://cdn-learn.adafruit.com/assets/assets/000/085/769/medium640/adafruit_products_IMG_8407.jpg?1576175930)

![adafruit_products_IMG_1784.jpg](https://cdn-learn.adafruit.com/assets/assets/000/085/770/medium640/adafruit_products_IMG_1784.jpg?1576175999)

![](https://cdn-learn.adafruit.com/assets/assets/000/085/756/medium800/adafruit_products_pi_hole_crop_1.png?1576174381)


## Featured Products

### Adafruit Raspberry Pi Zero Case

[Adafruit Raspberry Pi Zero Case](https://www.adafruit.com/product/3252)
This is a basic, classic **Pi Zero enclosure** with a black base and a clear top. The case is as minimal as it gets, coming in just two pieces of polycarbonate that snap snugly together. This case will keep your Pi Zero safe and secure while also looking super sleek. You...

In Stock
[Buy Now](https://www.adafruit.com/product/3252)
[Related Guides to the Product](https://learn.adafruit.com/products/3252/guides)
### Adafruit Mini PiTFT - 135x240 Color TFT Add-on for Raspberry Pi

[Adafruit Mini PiTFT - 135x240 Color TFT Add-on for Raspberry Pi](https://www.adafruit.com/product/4393)
If you're looking for the most compact li'l color display for a [Raspberry Pi](https://www.adafruit.com/category/361) (most likely a [Pi Zero](https://www.adafruit.com/category/813)) project, this might be just the thing you need!

The **...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/4393)
[Related Guides to the Product](https://learn.adafruit.com/products/4393/guides)
### Adafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry Pi

[Adafruit PiOLED - 128x32 Monochrome OLED Add-on for Raspberry Pi](https://www.adafruit.com/product/3527)
If you're looking for the most compact li'l display for a [Raspberry Pi](https://www.adafruit.com/category/361) (most likely a [Pi Zero](https://www.adafruit.com/category/813)) project, this might be just the thing you need!

The **Adafruit...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/3527)
[Related Guides to the Product](https://learn.adafruit.com/products/3527/guides)
### Raspberry Pi Zero W

[Raspberry Pi Zero W](https://www.adafruit.com/product/3400)
If you didn't think that the Raspberry Pi Zero could possibly get any better, then boy do we have a pleasant surprise for you! The new **Raspberry Pi Zero W** offers all the benefits of the Pi Zero v1.3, but with one big difference – **built-in...**

In Stock
[Buy Now](https://www.adafruit.com/product/3400)
[Related Guides to the Product](https://learn.adafruit.com/products/3400/guides)
### Raspberry Pi Zero W Basic Pack - Includes Pi Zero W

[Raspberry Pi Zero W Basic Pack - Includes Pi Zero W](https://www.adafruit.com/product/3409)
Remember those cereal commercials that would always say, "part of a complete breakfast"? Well the Pi Zero's a lot like that bowl of cereal - while it's great on its own, you need a lot of accessories to make it a complete meal.

The **Pi Zero W...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/3409)
[Related Guides to the Product](https://learn.adafruit.com/products/3409/guides)
### Raspberry Pi Zero W Budget Pack - Includes Pi Zero W

[Raspberry Pi Zero W Budget Pack - Includes Pi Zero W](https://www.adafruit.com/product/3410)
Remember those cereal commercials that would always say, "part of a complete breakfast"? Well the Pi Zero's a lot like that bowl of cereal - while it's great on its own, you need a lot of accessories to make it a complete meal.

The **Pi Zero W...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/3410)
[Related Guides to the Product](https://learn.adafruit.com/products/3410/guides)
### Raspberry Pi Zero W Starter Pack - Includes Pi Zero W

[Raspberry Pi Zero W Starter Pack - Includes Pi Zero W](https://www.adafruit.com/product/3411)
Remember those cereal commercials that would always say, "part of a complete breakfast"? Well the Pi Zero's a lot like that bowl of cereal - while it's great on its own, you need a lot of accessories to make it a complete meal. 

The **Pi Zero W...**

Out of Stock
[Buy Now](https://www.adafruit.com/product/3411)
[Related Guides to the Product](https://learn.adafruit.com/products/3411/guides)
### Raspberry Pi 3 - Model B - ARMv8 with 1G RAM

[Raspberry Pi 3 - Model B - ARMv8 with 1G RAM](https://www.adafruit.com/product/3055)
Did you really think the Raspberry Pi would stop getting better? At this point, we sound like a broken record, extolling on the new Pi’s myriad improvements like we’re surprised that the folks at the Raspberry Pi Foundation are continuously making their flagship board better. ...

In Stock
[Buy Now](https://www.adafruit.com/product/3055)
[Related Guides to the Product](https://learn.adafruit.com/products/3055/guides)

## Related Guides

- [Adafruit Mini PiTFT - Color TFT Add-ons for Raspberry Pi](https://learn.adafruit.com/adafruit-mini-pitft-135x240-color-tft-add-on-for-raspberry-pi.md)
- [PiTFT Python + Pillow Animated Gif Player](https://learn.adafruit.com/pitft-linux-python-animated-gif-player.md)
- [Adafruit Joy Bonnet for Raspberry Pi](https://learn.adafruit.com/adafruit-joy-bonnet-for-raspberry-pi.md)
- [Read-Only Raspberry Pi](https://learn.adafruit.com/read-only-raspberry-pi.md)
- [reef-pi Guide 1: Setup and Demonstration](https://learn.adafruit.com/reef-pi-installation-and-configuration.md)
- [Raspberry Pi Zero Stand](https://learn.adafruit.com/raspberry-pi-zero-stand.md)
- [Raspberry Pi Zero Headless Quick Start](https://learn.adafruit.com/raspberry-pi-zero-creation.md)
- [Turning your Raspberry Pi Zero into a USB Gadget](https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget.md)
- [Haunted Portrait](https://learn.adafruit.com/haunted-portrait.md)
- [Adafruit CharliePlex LED Matrix Bonnet](https://learn.adafruit.com/adafruit-charlieplex-bonnet.md)
- [LED Masquerade Masks with n00ds](https://learn.adafruit.com/led-masquerade-masks-with-n00ds.md)
- [AR1100 Resistive Touch Screen Controller Guide](https://learn.adafruit.com/ar1100-resistive-touch-screen-controller-guide.md)
- [Adafruit TLV493 Triple-Axis Magnetometer](https://learn.adafruit.com/adafruit-tlv493-triple-axis-magnetometer.md)
- [Adafruit BrainCraft HAT - Easy Machine Learning for Raspberry Pi](https://learn.adafruit.com/adafruit-braincraft-hat-easy-machine-learning-for-raspberry-pi.md)
- [Adafruit LIS3DH Triple-Axis Accelerometer Breakout](https://learn.adafruit.com/adafruit-lis3dh-triple-axis-accelerometer-breakout.md)
- [Adafruit Terminal PiCowbell for Pico](https://learn.adafruit.com/adafruit-terminal-picowbell-for-pico.md)