What files does Pi-hole use?

Note: FAQ updated in September 2022 to reflect files locations for Pi-Hole V5.12.


This directory is a clone of the pi-hole repo. During installation, the repository is cloned here so the files Pi-hole needs can be copied to your system.


  • pihole: the cron file that runs scheduled tasks such as rotating and flushing the log files or downloading the latest updates from the blocklist sources


  • 01-pihole.conf: the config specific to Pi-hole that controls how dnsmasq functions
  • 02-pihole-dhcp.conf: the config file used when Pi-hole's DHCP server is active
  • 04-pihole-static-dhcp.conf : file of static DHCP leases


  • lighttpd.conf: this is used to configure the Web server to respond to black holed domains and return a 404 of a blank Webpage. It also contains X-Headers and a few other settings.
  • external.conf: this is a user-created file that can be used to modify the Web server. These changes will persist through updates, unlike if you were to manually edit lighttpd.conf


This is where most of Pi-hole's config files exist. It contains:

  • adlists.list: a custom user-defined list of blocklist URL's (public blocklists maintained by Pi-Hole users)
  • blacklist.txt: a user-defined list of additional domains to block locally - legacy file (pre v5.x)
  • dhcp.leases: store Pi-hole's DHCP leases information
  • dns-servers.conf : The list of DNS servers that ship with Pi-Hole
  • gravity.db : database file with all of the domains that are being blocked - perhaps Pi-hole's most important database
  • install.log: a log file generated during installation
  • list.**.domain: these are the raw block lists that are downloaded.
  • local.list: this contains local list entries such as pi.hole so you can access the Web interface via name instead of IP.
  • logrotate: this is the config file that controls how logrotate handles flushing the log file
  • macvendor.db: a database of MAC addresses that relate the MAC address to a vendor (this file is updated when Pi-Hole is updated)
  • pihole-FTL.conf: this is the config file that specifies local pihole-FTL options
  • pihole-FTL.db: this is the long term Pi-Hole database, containing a record of queries and a network table of clients.
  • regex.list : file of regex filters that are compiled with each pihole-FTL start or restart - legacy file (pre v5.x)
  • setupVars.conf: this file contains variables needed to effectively setup and configure Pi-hole
  • versions: this file has information about the release version in GitHub and local versions
  • whitelist.txt: a user-defined list of domains to be whitelisted locally. Adding domains to this list makes them "gravity proof." - legacy file (pre v5.x)


  • individual scripts that are called by pihole
  • COL_TABLE: used for showing colors in the output of scripts



  • pihole-FTL.pid: the process ID used by FTL
  • pihole-FTL.port the port number used by FTL (defaults to 4711)


  • FTL.log: This is the log file that contains information handled by our FTL engine. This file is rotated every night at midnight.
  • pihole.log: This is the log file that contains all of the DNS queries Pi-hole handles as well as the queries that were blocked. See this post to learn how to interpret this file. This file is rotated every night at midnight.
  • pihole_debug.log: This is the log file generated by pihole -d. This is stored locally, but you also have the option to upload it to our secure server


  • access-pihole.log: this log contains entries from blocked domains (and the web interface). It is useful for visualizing Pi-hole.
  • error-pihole.log: this log file contains errors lighttpd may run into


  • This folder contains all the files needed for the admin interface and is simply a clone of the repo.


  • This folder contains the blank HTML page that is delivered in place of advertisements.
  • It also contains the blockpage if you try to directly visit a domain that is blocked

2 posts were split to a new topic: Multiple Pi-holes and pi.hole

A post was split to a new topic: What is /etc/.pihole/.git

This is a very useful list. It would be good if it identified the files/directories that must be preserved across reinstalls so these can be put in place prior to running the unattended installer. This would be useful when recreating containers or if rebuilding a physical machine.

I think it's worth noting, that when using Docker for pi-hole, amount of "exposed" to us (using bind command) is even smaller.

dnsmasq.d with two files:

01-pihole.conf 06-rfc6761.conf 


ll pihole/ | grep -v list
total 1.4G
-rw-r--r-- 1 root             root               16 Mar 12 18:44 GitHubVersions
-rw-r--r-- 1 systemd-coredump systemd-coredump    0 Mar 12 07:50 dhcp.leases
-rw-r--r-- 1 root             root              651 Mar 12 07:50 dns-servers.conf
-rw-rw-r-- 1 systemd-coredump systemd-coredump  76M Mar 13 13:33 gravity.db
-rw-rw-r-- 1 systemd-coredump systemd-coredump  76M Mar 13 04:21 gravity_old.db
-rw-r--r-- 1 root             root               20 Mar 13 14:20 localbranches
-rw-r--r-- 1 root             root               38 Mar 13 14:20 localversions
drwxr-xr-x 2 root             root             4.0K Dec  4 22:16 migration_backup
-rw-r--r-- 1 systemd-coredump systemd-coredump   20 Mar 12 07:50 pihole-FTL.conf
-rw-rw-r-- 1 systemd-coredump systemd-coredump 1.2G Mar 13 14:24 pihole-FTL.db
-rw-r--r-- 1 root             root              271 Mar 12 07:50 setupVars.conf

Everything else is just gravity related lists of domains.

This is very important (at least for me :slight_smile: ) because it makes backup and restore very easy to do. It's crucial to me i keep my history for long-term. With this setup i tar single folder and viola.