pi-hole/web: the dashboard that ships with Pi-hole

What pi-hole/web is, and what it is not

Pi-hole blocks ads and trackers network-wide through DNS. The blocking happens in FTLDNS, the resolver engine. pi-hole/web is the browser layer on top of it: a central place to manage the Pi-hole instance and review the statistics FTLDNS generates. That division matters. The repository holds no DNS logic and no blocking engine. It holds templates, styles and scripts that read from and write to the Pi-hole backend.

The audience is the person who already runs Pi-hole on their own Linux hardware and wants to see what their network is doing. The README lists what that means in practice: which domains are being queried, when the queries happened, how many were blocked, which upstream server received them, and the query types (A, AAAA, CNAME, SRV, TXT and others). If you do not run Pi-hole, this repository has nothing for you to point at.

One naming trap: the repository is pi-hole/web, but the thing it produces is the Pi-hole web interface or dashboard. The README calls it the Web interface throughout, and the interface is based on AdminLTE, the admin template library. The package.json name is pi-hole-web-interface and it is marked private, so there is no npm package of that name to install.

How the interface is put together

The top level of the repository tells you the architecture before you read a line of code. Pages are .lp files: index.lp, login.lp, queries.lp, network.lp, taillog.lp, search.lp, plus one settings-*.lp file per settings area (api, dhcp, dns, dnsrecords, privacy, system, teleporter, all). Group management gets its own set: groups.lp, groups-clients.lp, groups-domains.lp, groups-lists.lp. Error pages are error403.lp and error404.lp.

That .lp extension is the first thing to understand. These are not plain HTML files you can open from disk. They are server-side templates rendered by the Pi-hole web server before they reach the browser, which is why the README can point you at /admin/ as a URL rather than a file. The front end itself is deliberately conventional: jQuery 3.7.1, Bootstrap 3.4.1, AdminLTE 2.4.18, Chart.js 4.5.1 with the moment adapter and the zoom and deferred plugins, DataTables for the tables, daterangepicker for time ranges, select2 and bootstrap-select for the form controls, and Font Awesome for icons. The dependency list in package.json reads like a snapshot of a mature Bootstrap 3 admin stack rather than a modern build-tool project.

That is a trade-off worth naming. Bootstrap 3.4.1 and AdminLTE 2.4.18 are old lines. Keeping them means the interface stays visually consistent with years of documentation, screenshots and user expectations, and it avoids a rewrite of every template. It also means the front end inherits the constraints of those libraries. The JavaScript is checked by xo and formatted by prettier, which suggests the project cares about consistency within that stack rather than replacing it.

Installing it and logging in for the first time

There is no separate installation. The README states plainly that the web interface is enabled by default when you install Pi-hole, so the install step is installing Pi-hole itself. The repository does not document an alternative path, and package.json marks the package private, so npm install is not the route.

Once Pi-hole is running, the README gives three ways in. The first uses the IP address of the machine:

https://<IP_ADDRESS_OF_YOUR_PI_HOLE>/admin/

Replace the placeholder with your Pi-hole host's address. The README notes you can use either http:// or https:// protocols. The second and third options require the client to be using Pi-hole as its DNS server, because they rely on the pi.hole hostname resolving:

https://pi.hole/admin/
https://pi.hole/

If pi.hole does not resolve, your client is not pointed at Pi-hole for DNS yet, and the IP form is the one that will work. After the page loads you are asked to log in; the README shows password protection as a feature and login.lp exists in the repository root, which is the page behind that prompt. Once logged in, the dashboard presents the network statistics described above. The query log is where most people spend their time: the README says it shows recent and long-term data over user-defined time ranges, with an advanced filter for narrowing the log. That filter is the practical starting point for answering a specific question, such as which client is generating traffic to a particular domain.

What you can change from the dashboard, and what you cannot

The settings-*.lp files map the administrative surface almost one to one. There is a page for DNS settings, one for DHCP, one for local DNS records, one for API settings, one for privacy, one for system settings, and one for Teleporter, the export and import feature. Blocking and allowing gets its own handling: the README describes lists, domains (block or allow) and regex entries as part of the interface, and the groups-*.lp files show that client groups, domain groups and list groups are managed here too.

What the interface cannot do is act on data the backend has not collected. The dashboard is a view over FTLDNS statistics, so if query logging is off or privacy settings are restricting what is recorded, the graphs and the query log will be correspondingly thin. The privacy settings page exists precisely because that trade-off is real, and it is the first place to look when the dashboard seems to be missing activity you know happened.

The other boundary is version skew. The interface and the Pi-hole core are released separately. This repository's recent releases are v6.6 (2026-07-06), v6.5.1 (2026-06-14) and v6.5 (2026-04-03), and the last push to the repository was on 2026-09-23. A dashboard version and a core version that do not match is a plausible source of confusing behaviour, and nothing in the README describes a compatibility matrix between them.

Where pi-hole/web is the wrong tool

The clearest failure case is treating this as a general-purpose DNS dashboard. It is not. It reads Pi-hole's own data through Pi-hole's own server. Point it at a BIND server or a dnsmasq instance that is not part of a Pi-hole install and there is no data path. The .lp templates expect the Pi-hole backend to render them.

The second case is a network where you cannot control DNS. Pi-hole works by being the resolver your clients use. If your clients are hardcoded to an external resolver, or your router will not hand out Pi-hole's address over DHCP, the dashboard will faithfully show you an almost empty query log. That is not an interface bug; it is the interface reporting an empty backend.

Third, the README's own framing is a constraint. It describes Pi-hole as network-wide ad blocking via your own Linux hardware. That sentence sets the deployment assumption. If your environment is Windows-only, the README offers no Windows installation path for the interface, and the repository is a set of server-rendered templates rather than a desktop application. The search questions people ask about running Pi-hole on Windows are not answered by this repository's documentation.

Finally, anyone expecting a documented rollback path for the interface will not find one. The README does not document rollback, and Teleporter is described as an export and import feature rather than a version control mechanism for the interface itself.

How it differs from a standalone DNS dashboard

The obvious alternative in this space is a self-hosted dashboard that talks to a resolver's API, such as AdGuard Home's built-in web UI. The difference is architectural, not cosmetic. AdGuard Home bundles the resolver and the interface as one program with one version number and one install. Pi-hole splits them: FTLDNS does the resolving and blocking, and pi-hole/web is the template layer served alongside it. That split is why this repository has its own release cadence (v6.5, v6.5.1, v6.6) separate from the core, and why the README can say the interface is enabled by default when you install Pi-hole rather than telling you how to install the interface.

A second comparison is running Pi-hole headless and querying it from the command line. That works, and it is lighter. What you give up is the specific things the README lists as features: the doughnut charts, the top lists of domains and clients, the query log with its advanced filter, the mobile-friendly layout, and the settings pages for DNS, DHCP, local records and groups. Editing a regex blocklist entry through a form is a different task from editing it in a config file, and for a home network the form is usually the faster path.

The honest read is that pi-hole/web is not competing with standalone dashboards. It is the interface for one specific resolver, and it is maintained by the same organisation that maintains that resolver.

Licence, maintenance and upgrade cost

The repository's LICENSE file is present at the top level, and package.json declares "license": "EUPL-1.2". The repository metadata reports the licence as NOASSERTION, which means the automated classifier did not resolve it; the package.json field is the more specific signal, and the LICENSE file is the authoritative text. EUPL-1.2 is a copyleft licence, so if you plan to redistribute modified templates, read the LICENSE file rather than assuming permissive terms. This is a description of what the files say, not legal advice.

On maintenance: the repository is not archived, and the last push was on 2026-09-23, days before this writing. The release history shows a steady cadence through 2026. That said, the dependency set is the thing to watch on upgrade. Bootstrap 3.4.1, AdminLTE 2.4.18 and DataTables 1.10.21 are pinned versions from older lines, and the scripts that consume them are checked with xo and prettier. Upgrading a single dependency in that stack is unlikely to be a one-line change, because the templates were written against the behaviour of those specific versions.

The practical upgrade cost for a user is low, because you are not building the interface yourself. You upgrade Pi-hole and the interface moves with it. The cost lands on contributors and on anyone forking the templates, who inherit the pinned front-end stack and the .lp rendering model.

Editorial conclusion

Adopt pi-hole/web when you already run Pi-hole and want the query log, top lists and blocklist editing in a browser rather than a terminal; it is the interface the project maintains for exactly that job. Do not adopt it as a standalone dashboard for a third-party DNS resolver, and do not expect the repository to give you an install path, because the README states the web interface is enabled by default when you install Pi-hole. Before relying on it, confirm two things against your own deployment: that the dashboard answers at https://pi.hole/admin/ on your network, and that your Pi-hole package version matches the interface version you are reading about, since the two are released separately. Treat the package.json license field, EUPL-1.2, as the identifier to check against the LICENSE file before redistributing any part of the templates.

Frequently asked questions

Official sources

1. Issues
2. pi-hole/web on GitHub
3. Project website
4. README
5. Releases