pihole command lets you control, configure, and update your Pi-hole.
Press tab after writing
pihole to see the available options.
Control all Pi-hole specific functions!
Usage: pihole [options]
Add -h after -w (whitelist), -b (blacklist), -c (chronometer), or -a (admin) for more information on usage
-w, whitelist Whitelist domain(s)
-b, blacklist Blacklist domain(s) (exact match)
-wild, wildcard Blacklist whole domain(s) (wildcard)
-d, debug Start a debugging session
Automated debugging can be enabled with 'pihole -d -a'
-f, flush Flush the 'pihole.log' file
-t, tail Output the last lines of the 'pihole.log' file. Lines are appended as the file grows
-up, updatePihole Update Pi-hole components
-r, reconfigure Reconfigure or Repair Pi-hole
-g, updateGravity Update the list of ad-serving domains
-c, chronometer Calculates stats and displays to an LCD
-h, help Show this help dialog
-v, version Show installed versions of Pi-Hole and Web-Admin
-q, query Query the adlists for a specific domain
'pihole -q domain -exact' shows exact matches only
-l, logging Enable or Disable logging (pass 'on' or 'off')
-a, admin Admin webpage options
uninstall Uninstall Pi-Hole from your system :(!
status Is Pi-Hole Enabled or Disabled
enable Enable Pi-Hole DNS Blocking
disable Disable Pi-Hole DNS Blocking
Blocking can also be disabled only temporarily, e.g.,
'pihole disable 5m' - will disable blocking for 5 minutes
restartdns Restart dnsmasq
checkout Check out different branches
Whitelist or Blacklist A Domain
This is one of the most common things you might do with the
pihole command (see commonly whitelisted or blacklisted domains)
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
Some 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, 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 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.
During the debug process, you will be prompted to navigate to some troublesome sites, so the data is captured by the debugger.
Send 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:
::: Would you like to upload the log? [y/N] y
::: ---=== Your debug token is : h4kw2r42i0 Please make a note of it. ===---
::: Contact the Pi-hole team with your token for assistance.
So when you contact us for help, you would provide us with the token
h4kw2r42i0 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
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 does a lot of the magic by downloading 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.
This command will show you some real-time stats on the command line. It works if you have an LCD screen setup per above, but it also works over SSH if you just want to hop in and watch some formatted stats roll by (see also Logstalgia).
Ad List Query
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
and it will return the list the domain was originally found on. This proved useful a while back when the Mahakala list was adding apple.com and microsoft.com to their block list.
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.
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.
pihole -a -p with no arguments to remove any previously set password.
Adjust The Temperature Unit
pihole -a -c
pihole -a -f
pihole -a -k
Change the listening interface
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).
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.
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
development open 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.