pihole command lets you control, configure, and update your Pi-hole.
Press tab after writing
pihole to see the available options.
Usage: pihole [options] Example: 'pihole -w -h' Add '-h' after specific commands for more information on usage Whitelist/Blacklist Options: -w, whitelist Whitelist domain(s) -b, blacklist Blacklist domain(s) -wild, wildcard Blacklist domain(s), and all its subdomains Add '-h' for more info on whitelist/blacklist usage Debugging Options: -d, debug Start a debugging session Add '-a' to enable automated debugging -f, flush Flush the Pi-hole log -r, reconfigure Reconfigure or Repair Pi-hole subsystems -t, tail View the live output of the Pi-hole log Options: -a, admin Admin Console options Add '-h' for more info on admin console usage -c, chronometer Calculates stats and displays to an LCD Add '-h' for more info on chronometer usage -g, updateGravity Update the list of ad-serving domains -h, --help, help Show this help dialog -l, logging Specify whether the Pi-hole log should be used Add '-h' for more info on logging usage -q, query Query the adlists for a specified domain Add '-h' for more info on query usage -up, updatePihole Update Pi-hole subsystems -v, version Show installed versions of Pi-hole, Admin Console & FTL Add '-h' for more info on version usage uninstall Uninstall Pi-hole from your system status Display the running status of Pi-hole subsystems enable Enable Pi-hole subsystems disable Disable Pi-hole subsystems Add '-h' for more info on disable usage restartdns Restart Pi-hole subsystems checkout Switch Pi-hole subsystems to a different Github branch Add '-h' for more info on checkout usage
Usage: pihole -a [options] Example: pihole -a -p password Set options for the Admin Console Options: -p, password Set Admin Console password -c, celsius Set Celsius as preferred temperature unit -f, fahrenheit Set Fahrenheit as preferred temperature unit -k, kelvin Set Kelvin as preferred temperature unit -r, hostrecord Add a name to the DNS associated to an IPv4/IPv6 address -e, email Set an administrative contact address for the Block Page -h, --help Show this help dialog -i, interface Specify dnsmasq's interface listening behavior Add '-h' for more info on interface usage
Whitelist or Blacklist A Domain
Usage: pihole -w [options] <domain> <domain2 ...> Example: 'pihole -w site.com', or 'pihole -w site1.com site2.com' Whitelist one or more domains Options: -d, --delmode Remove domain(s) from the whitelist -nr, --noreload Update whitelist without refreshing dnsmasq -q, --quiet Make output less verbose -h, --help Show this help dialog -l, --list Display all your whitelisted domains --nuke Removes all entries in a list
Usage: pihole -b [options] <domain> <domain2 ...> Example: 'pihole -b site.com', or 'pihole -b site1.com site2.com' Blacklist one or more domains Options: -d, --delmode Remove domain(s) from the blacklist -nr, --noreload Update blacklist without refreshing dnsmasq -q, --quiet Make output less verbose -h, --help Show this help dialog -l, --list Display all your blacklisted domains --nuke Removes all entries in a list
pihole -w spclient.wg.spotify.com
Blacklist Twitch (appending multiple domains to the command)
pihole -b api.mixpanel.com spade.twitch pubads.g.doubleclick.net sb.scorecardresearch.com
WildcardingSome ad networks have several subdomains that all server advertisements. Instead of blacklisting each one individually, you may want to block all of a subdomain to a certain point. As an example, pubnub.com has several subdomains:
Instead of blacklisting each one individually, you can pass the
-wild flag to block the entire set of subdomains.
pihole -wild pubnub.com
will achieve the same effect.
You can also remove these wildcard entries with the
pihole -wild -d pubnub.com
Debug Your Pi-hole Install
Our debug script will run through some diagnostics and (optionally) automatically upload this log to our secure server. It will generate a unique token, which you can provide to the Pi-hole dev team if you need help.
pihole -d -a
if you don’t want the log to be uploaded automatically, just run
and the log will be saved locally.
Sending The Debug Token To The Development Team
If you choose to upload your debug log to our secure server, you will be given a random string of characters, which is your debug token. It will look something like this. When the command is finished running, you will see a message like this:
[?] Would you like to upload the log? [y/N] y * Using openssl for transmission. *********************************** *********************************** [✓] Your debug token is: xamtybzux1 <-----provide us this *********************************** ***********************************
So when you contact us for help, you would provide us with the token
xamtybzux1 and then we could look at your log file.
Flushing The Log File
Depending on your system and how heavily your Pi-hole is used, you may want to flush the log throughout the day. By default, the log if flushed at the end of the day via
cron, but a very large log file can slow down the Web interface, so flushing it can be useful. Just run
NOTE: if you flush the log, some of the stats will not be processed by FTL and thus may not show up in long-term stats.
Tailing The Log File
Pi-hole logs DNS queries by default (this can be turned off when installing). Watching this log file in real-time can be useful for debugging a problematic site. You can also use it purely for curiosity. Since you will see domain queries come up in real-time you can see what is happening on your network.
will start the log rolling. Press Control + c to stop viewing the log.
Interpreting The Log
The log file can be a bit confusing, so take a look at this article to help understand what you are looking at.
will update your Pi-hole to the latest version.
This command will show you some real-time stats on the command line. It works if you have an LCD screen, but it also works over SSH if you just want to hop in and watch some formatted stats roll by (see also Logstalgia).
You will be presented with some ASCII text that auto-refreshes.
Pi-hole Chronometer Press Ctrl-C to exit —————————————————————————————————————————————————————————— Hostname: debian (Debian Jessie 8) Uptime: 4 days, 23:54:43 Task Load: 0.00 0.03 0.01 (Active: 1 of 31 tasks) CPU usage: 2% (2.4 GHz) RAM usage: 20% (Used: 98 MB of 494 MB) HDD usage: 7% (Used: 1 GB of 20 GB) LAN addr: 220.127.116.11 (Gateway: 18.104.22.168) Pi-hole: Active (Blocking: 106012 sites) Ads Today: 0% (Total: 4 of 4097) Local Qrys: 81% (2 DNS servers) Blocked: shs.grafixreview.com Top Advert: shs.grafixreview.com Top Domain: 220.ip-79-137-39.eu Top Client: localhost
Press Ctrl+C at anytime to stop the script.
This command is crucial to Pi-hole as it downloads and processes ad block lists from several sources and combining them into a single
gravity.list hosts file, which is used to block ads. Run it with
This will for a download of any updates from the third-party block lists that we source. By default, this command runs once a week via
cron, so there’s no need to run it manually unless you want to get some updated lists or you run into a problem with the list.
Ad List Query
Usage: pihole -q [option] <domain> Example: 'pihole -q -exact domain.com' Query the adlists for a specified domain Options: -adlist Print the name of the block list URL -exact Search the block lists for exact domain matches -all Return all query matches within a block list -h, --help Show this help dialog
This command is useful to find out what domain a list appears on. Since we don’t control what the third-parties put on the block lists, you may find that a domain you normally visit stops working. If this is the case, you could run
pihole -q somedomain.com
Use can use the
-exact flag to find an exact match, otherwise it will just search for your phrase, so
pihole -q hulu
will return any domain with hulu in it, and
pihole -q t2.hulu.com -exact
will only search for t2.hulu.com.
Usage: pihole logging [options] Example: 'pihole logging on' Specify whether the Pi-hole log should be used Options: on Enable the Pi-hole log at /var/log/pihole.log off Disable the Pi-hole log at /var/log/pihole.log
You can turn off logging:
pihole -l off
and turn it back on:
pihole -l on
This can be useful if you don’t want queries logged for a certain time.
Administer The Web Interface
You will mainly use this command to set or reset a password for the interface (a default password is generated at install), but you can also use it to adjust the temperature unit.
Set A Web Interface Password
pihole -a -p somepassword
will set a new password for your admin interface.
Adjust The Temperature Unit
You can also change the temperature unit to celsius:
pihole -a -c
pihole -a -f
pihole -a -k
Change the listening interface
Usage: pihole -a -i [interface] Example: 'pihole -a -i local' Specify dnsmasq's network interface listening behavior Interfaces: local Listen on all interfaces, but only allow queries from devices that are at most one hop away (local devices) single Listen only on eth0 interface all Listen on all interfaces, permit all origins
pihole -a -i local
Will set Pi-hole to listen on all interfaces, but allow only queries from devices that are at most one hop away (local devices). This is the default behavior, which also helps prevents open resolvers.
pihole -a -i single
Will tell Pi-hole to listen on a single interface (see PIHOLE_INTERFACE).
pihole -a -i all
Will set Pi-hole to listen on all interfaces, while permitting all origins (requests from outside your network).
Add a name to the DNS associated to an IPv4/IPv6 address Options: "" Empty: Remove host record -h, --help Show this help dialog
This flag lets you assign a name to an IP address. This is useful for recognizing clients in the query log.
pihole -a myrouter home.domain.com 192.168.1.1
Usage: pihole -a email <address> Set an administrative contact address for the Block Page Options: "" Empty: Remove admin contact -h, --help Show this help dialog
This flag allows you to set an email address that appears in the block page. This is useful in large environments when an end-user comes across a blocked site and wants to contact someone for more information.
Just enter an email address as an argument:
pihole -a -e firstname.lastname@example.org
You can uninstall Pi-hole by running
You will have the option to choose which packages will be removed in case you use them for other services on your machine.
Enabling Or Disabling Pi-hole
You can disable Pi-hole using
but you can also pass a time argument to disable Pi-hole for a certain amount of time:
pihole disable 10m
will disable Pi-hole for 10 minutes. Please note that you may not see the effects unless you flush your cache. You can use
m for minutes or
s for seconds.
pihole disable 60s
will disable Pi-hole for sixty seconds.
Checking If Blocking Is Enabled
You can check the current status of Pi-hole using
You can restart the DNS server with
this will force a reload of
dnsmasq at which time it will also reload the config file and the hosts file.
Usage: pihole -v [repo | option] [option] Example: 'pihole -v -p -l' Show Pi-hole, Admin Console & FTL versions Repositories: -p, --pihole Only retrieve info regarding Pi-hole repository -a, --admin Only retrieve info regarding AdminLTE repository -f, --ftl Only retrieve info regarding FTL repository Options: -c, --current Return the current version -l, --latest Return the latest version --hash Return the Github hash from your local repositories -h, --help Show this help dialog
The version flag has a lot of options. As our software is broken out into three main pieces, there are versions for each.
Checkout different branches of the project
WARNING: the development branch is not considered stable for general use. We regularly push changes to it so don’t be surprised if something is broken. If you do find an issue in
developmentopen an issue on GitHub so we can take a look.
You can checkout what’s happening in our development environment by using this command. Under the hood, it’s just running a series of
git commands, but you’ll probably find this more convenient.
In most cases, you will want to check out both the Core code and the Web code, as the two often are dependent on one another. To checkout development branches on both repos, use:
pihole checkout dev
To return to the stable to codebase, just run:
pihole checkout master
Finally, if you deep into the code, you may want to check out a branch other than
development. Just use;
pihole checkout core somebranch
to checkout just the core code, or
pihole checkout web somebranch
for the Web code.