jacklul/pihole-updatelists for Pi-hole

Why pihole-updatelists exists for remote Pi-hole lists

jacklul/pihole-updatelists addresses a specific gap in Pi-hole v6 deployments. A Pi-hole instance can use blocklists hosted by remote services, but those sources change independently of the local Pi-hole database. The README describes manually checking remote lists and importing their changes as a hassle. This project is for administrators who maintain such remote lists and need a repeatable way to bring local entries into line with them.

The project is not a general-purpose Pi-hole management system. Its README explicitly warns that it is useless for installations that do not use remote lists, because Pi-hole already updates its lists weekly automatically. That limitation matters when deciding whether the added PHP process, scheduler, configuration file, and database maintenance are justified. A fresh Pi-hole v6 installation is preferred, although the project can be installed on an existing system after its lists have been migrated.

The implementation is primarily PHP, with shell scripts for installation and Docker-related operation. The repository contains `pihole-updatelists.php`, `pihole-updatelists.bash`, `pihole-updatelists.conf`, `install.sh`, a service and timer unit, and a `Dockerfile`. This layout indicates a small host-side utility rather than a fork of Pi-hole itself. It works with Pi-hole's local gravity database and invokes Pi-hole commands where needed, so Pi-hole remains the component responsible for the DNS and gravity environment.

The managed-entry model and Pi-hole database changes

The defining behavior is preservation of local work during synchronization. According to the README, user-created entries are not touched. Entries removed from a remote list are disabled rather than deleted outright. That distinction matters because local custom domains and allowlist-style entries can remain separate from remote-managed data instead of being treated as disposable imported records.

The README's migration guidance identifies the mechanism for ownership. Existing imported remote entries must be marked so the project can recognize them. For lists imported with pihole5-list-tool, the documented SQL updates set matching adlist and domainlist comments to `Managed by pihole-updatelists`. For manually imported lists, administrators are told to modify the comment fields themselves, delete the imported entries through the web interface, or recreate the Pi-hole lists. Manual comment modification is described as recommended, although potentially laborious.

This model depends on Pi-hole v6 and its `gravity.db` SQLite database. The migration examples update the `adlist` and `domainlist` tables directly with `sqlite3`, which means the utility is tied to Pi-hole's data layout rather than treating Pi-hole as a black-box HTTP API. The README does not provide a detailed compatibility matrix for other Pi-hole database schemas, so an administrator should treat the stated v6 requirement as a deployment constraint rather than assuming compatibility with older releases.

Installing the PHP utility and scheduling its first update

The documented installation command downloads `install.sh` from the repository and runs it with `sudo`. It installs the script to `/usr/local/sbin`. Depending on the host, the installer also creates systemd service and timer units or writes a cron entry at `/etc/cron.d/pihole-updatelists`. The README also allows cloning the repository and running `sudo bash install.sh` instead.

On Debian, the documented package command installs the CLI and several required PHP packages:

apt install php-cli php-sqlite3 php-curl php-intl

The README lists the required extensions as `filter pdo pdo_sqlite curl openssl intl pcntl posix`. Their package names vary by distribution. For example, the Alpine command includes several explicitly named packages:

apk add php php-pdo_sqlite php-curl php-openssl php-intl php-pcntl php-posix

After installation, configure the project before expecting it to update remote lists. By default, the script does nothing except run `pihole updateGravity`, according to the README. Once configuration is in place, the first manual invocation is:

sudo pihole-updatelists

The command is usually available globally as `pihole-updatelists`, although some hosts require `/usr/local/sbin` in `$PATH` or require the full path. The script can also check for script differences and rerun the installer when an update is requested:

sudo pihole-updatelists --update

The README does not document a dry-run mode, a rollback command, or a complete description of every configuration key. Those details should be checked in `pihole-updatelists.conf` and `pihole-updatelists.php` before using the utility on a production Pi-hole instance.

systemd, cron, and the duplicated gravity schedule

Scheduling depends on the host. The README recommends systemd but treats it as optional. With systemd, the installer adds a service and timer unit. Without it, the installer creates `/etc/cron.d/pihole-updatelists`. If systemd appears available but the installer fails to copy its units, the README documents a forced installation form:

sudo bash -s systemd

That command is shown as a variation on the remote install command, so administrators should pass it only when the scheduler choice must be forced.

The project also intersects with Pi-hole's own `updateGravity` schedule. The README says the script runs `pihole updateGravity`, while Pi-hole's cron entry normally runs it weekly. To avoid two schedules operating on the same installation, the documented cron entry can be commented out manually:

sudo nano /etc/cron.d/pihole

The example entry is changed by adding `#` before its cron command. The README also provides a targeted `sed` command:

sudo sed -e '/pihole updateGravity/ s/^#*/#/' -i /etc/cron.d/pihole

This is a host-level change. The README warns that a Pi-hole update may require repeating it. It also shows a systemd service override intended to disable the cron entry after updates, using `pihole-FTL.service` and `ExecStartPre`. The override is more involved than the basic cron edit, and administrators should inspect the generated service before adopting it.

Docker deployment for jacklul/pihole

The project provides Docker-specific installation paths. The README tells Docker users to follow the official Pi-hole instructions but replace the image with `jacklul/pihole:latest`. Configuration variables can be passed as environment variables in `docker-compose.yml`. That image contains a version of the script available when the image was published, which means the Docker path introduces an image release cycle separate from a local checkout.

The repository also contains a `Dockerfile` based on `pihole/pihole:latest`. It installs the PHP packages needed by the script, copies the installation files into a temporary directory, runs the Docker installer, and removes the temporary files. The documented package line is:

FROM pihole/pihole:latest

RUN apk add --no-cache php php-pdo_sqlite php-curl php-openssl php-intl php-pcntl php-posix && \
    bash /tmp/pihole-updatelists/install.sh docker && \
    rm -fr /tmp/pihole-updatelists

The repository's `Dockerfile` additionally copies `install.sh`, `docker.sh`, and `pihole-updatelists.*` into that directory before running the installer. A custom image gives the administrator control over the base Pi-hole image and script version, but the README states that a locally built image must be updated manually when a new script release is available.

The Docker approach is therefore a trade-off. A published `jacklul/pihole:latest` image is convenient, while a custom image adds an explicit image build and update step. The repository has no GitHub releases, so the README does not establish a formal release cadence for the image or the installer.

Limitations, maintenance, and the MIT license

The main limitation is scope. This utility does not replace Pi-hole's built-in list updating, and it has little value on a fresh configuration without remote sources. It also requires direct interaction with Pi-hole's SQLite database during migration and depends on PHP extensions that are packaged differently across Linux distributions. The README does not document rollback, a complete backup procedure, or behavior for incompatible Pi-hole database schemas.

Maintenance status should be assessed from repository activity rather than promotional wording. The repository is not archived, and its last push was on 2026-06-20. GitHub has no releases for the repository. The README warns that Pi-hole updates may restore a cron entry that an administrator disabled, and that custom Docker images require manual updates. These are concrete maintenance costs associated with the deployment model.

The project is distributed under the MIT license. That license permits use and modification under its terms, but administrators still need to review the license text and comply with its notice and disclaimer requirements. The README does not provide a support policy, compatibility guarantee, or long-term support schedule. The appropriate adoption decision depends on whether remote-list synchronization is a real operational need and whether the host can accommodate the PHP, database, and scheduler changes.

Editorial conclusion

Adopt this project if you operate Pi-hole v6 with manually managed remote lists and need scheduled synchronization, especially in Docker or on a system without systemd. Do not adopt it for a standard Pi-hole installation that relies only on its weekly automatic gravity updates. First verify the configuration, migration requirements, scheduler integration, and whether the Docker image or local install method fits the deployment model. The project is not a general Pi-hole replacement, and its last push was on 2026-06-20.

Frequently asked questions

Official sources

1. Issues
2. jacklul/pihole-updatelists on GitHub
3. License: MIT
4. README