Pi-hole Teleporter is more than just a backup tool; it’s a way to instantly clone a Pi-hole’s entire state, from blocklists and DNS settings to custom entries and even its UI theme.
Let’s see Teleporter in action. Imagine we have a primary Pi-hole server, pihole-primary, running at 192.168.1.10. We want to replicate its configuration to a new, identical setup, pihole-secondary, at 192.168.1.11.
First, on pihole-primary, we navigate to Settings -> Teleporter. We see a button labeled "Backup". Clicking this generates a .tar.gz file, pihole-teleporter_backup_YYYY-MM-DD_HH-MM-SS.tar.gz. This file contains everything:
/etc/pihole/gravity.db: The main database with all lists and cached domains./etc/pihole/local.list: Custom regex and domain entries./etc/pihole/adlists.list: The list of upstream blocklists./etc/pihole/queries.log(if enabled for logging)/etc/pihole/pihole-FTL.conf: The FTL configuration file./var/www/html/admin/assets/css/custom.css: For UI theme customization.- And other relevant configuration files.
We download this file. Now, on pihole-secondary, which has a fresh Pi-hole installation, we go to the same Settings -> Teleporter page. This time, we find an "Upload" section. We click "Choose File", select our downloaded backup, and click "Restore".
Pi-hole will then unpack this archive and apply all the settings. After a brief moment, the pihole-secondary web interface will refresh, and it will look and behave exactly like pihole-primary. If pihole-primary had 500,000 blocked domains, pihole-secondary will now have 500,000 blocked domains. If you had custom regex filters like ^([a-z0-9-]+\.)*example\.com$, they’ll be there too.
The core problem Teleporter solves is the tediousness and error-proneness of manually reconfiguring Pi-hole instances. Think about setting up a Pi-hole for a friend, or migrating to new hardware, or even just testing a new configuration. Doing this manually involves SSHing in, editing multiple files, running pihole -g to update gravity, and potentially fiddling with web UI settings. Teleporter collapses all of that into a single file transfer and a button click.
Internally, the Teleporter script (/usr/local/bin/pihole with the teleporter subcommand) essentially creates a compressed archive. The backup action uses tar to bundle the specified configuration directories and files. The restore action unpacks this archive, overwrites existing files (after backing them up to a _backup directory), and then intelligently restarts the necessary services (pihole-FTL, lighttpd) and triggers a gravity update (pihole -g). It’s designed to be a full state snapshot.
The exact levers you control are the configuration files themselves. While Teleporter bundles most things, understanding what’s in the archive helps. For example, if you only want to transfer your custom blocklists and regex entries, you could theoretically extract just those specific files from the backup archive and manually place them on another Pi-hole, then run pihole -g. However, Teleporter is designed for the full-system, atomic restore.
One surprising detail about Teleporter is its handling of the FTL configuration. While pihole-FTL.conf is included, certain network-specific settings like the static IP address of the Pi-hole itself (if configured) are not automatically applied during restore. The restore process will overwrite the file, but the underlying network interface configuration on the OS level is independent. If you restore to a machine with a different IP address, you’ll need to manually update the Pi-hole’s IP address in the OS’s network configuration and then run pihole -r (reconfigure) to tell Pi-hole about its new IP.
The next concept you’ll likely encounter is understanding how to automate this backup and restore process, perhaps for disaster recovery scenarios.