EliHole imports Pi-hole Teleporter backups natively. You export a .tar.gz from Pi-hole, upload it on EliHole’s settings page, and your blacklists, whitelists, adlists, upstream DNS servers, and local DNS records carry over in one step — no conversion scripts, no manual re-entry. Most migration guides for Pi-hole alternatives revolve around Python scripts that translate Teleporter archives into another tool’s format; here the archive is the import format.
The whole process takes about five minutes of hands-on work: export, install, import, validate, switch. This page walks through each step and is honest about the one thing that does not transfer.
Why migrate at all
Pi-hole is solid software, and if it covers everything you need, there is no urgency to leave. The practical reasons people switch to EliHole are the features Pi-hole does not ship out of the box:
- Encrypted DNS built in — DNS-over-HTTPS (RFC 8484) and DNS-over-TLS (RFC 7858) without bolting on a separate proxy.
- Enforced DNSSEC validation — full chain-of-trust checking on responses, not just passthrough.
- Native master-slave clustering — a second resolver that stays in sync without third-party sync scripts.
- CNAME-cloaking deep inspection — trackers hiding behind CNAME chains get caught.
- Native Prometheus metrics — a
/metricsendpoint, no exporter sidecar.
If you want the detailed side-by-side, the full feature comparison covers both directions, including where Pi-hole still has the edge. The rest of this page assumes you have decided to move.
Step 1: export a Teleporter backup from Pi-hole
In the Pi-hole admin panel, go to Settings → Teleporter and click Export. Pi-hole generates a .tar.gz archive and your browser downloads it.
That single file contains everything EliHole will read: your exact and regex blacklists, exact and regex whitelists, adlist subscriptions, upstream DNS configuration, and local DNS records. Keep it somewhere you can reach from the browser you’ll use for EliHole’s admin panel.
Leave Pi-hole running. It keeps serving your network until step 5, and a working fallback makes the whole migration low-stakes.
Step 2: install EliHole
If EliHole isn’t running yet, follow the Docker install guide — it covers the Compose setup, environment variables, and the port 53 options. The short version is cp .env.example .env, set three variables, and docker compose up -d.
One migration-specific tip: since Pi-hole is still occupying port 53 on your network, run EliHole on its default port 5354 (or on a different host) during the transition. You don’t need both resolvers answering on port 53 at the same time — clients only see EliHole after step 5.
Confirm the new instance answers before importing anything:
dig @<elihole-host> -p 5354 google.comStep 3: import the backup
Open EliHole’s admin panel and go to /admin/settings. In the Teleporter import/export section, upload the .tar.gz you exported in step 1.
EliHole auto-detects the backup format — it accepts both Pi-hole Teleporter archives and its own exports, so there is nothing to select or convert. The import brings in:
- Blacklists — exact-match and regex entries
- Whitelists — exact-match and regex entries
- Adlists — your subscription URLs, in the same format Pi-hole uses
- DNS providers — your upstream resolvers
- Local DNS records — entries in Pi-hole’s
custom.listformat
Anything EliHole cannot map — clients and groups — is skipped and listed in the import report, so you know exactly what didn’t make it rather than discovering it later. More on that in what doesn’t transfer.
After the import, adlists are live subscriptions, not a frozen snapshot: EliHole refreshes them automatically every 24 hours with up to 4 parallel downloads and deduplication across lists, and you can trigger a manual refresh with Update Now.
If you also maintain host entries outside Teleporter, the local DNS bulk import accepts Pi-hole’s custom.list and standard /etc/hosts format, so you can paste those straight in too.
Step 4: validate before switching
With Pi-hole still serving the network, point some test queries at EliHole directly.
A domain that should resolve:
dig @<elihole-host> -p 5354 google.comA domain on your blocklist — it should come back blocked:
dig @<elihole-host> -p 5354 doubleclick.netThen open the query log at /admin/queries and watch the entries arrive in real time. Check three things:
- Blocked domains show as blocked.
- A domain you whitelisted resolves even if a blocklist contains it — whitelist always overrides blocklist in EliHole, the same semantics as Pi-hole, so your exceptions behave identically.
- Your local DNS records answer with the addresses you expect.
If you imported regex rules, test a domain that only a regex should catch. Regex behavior is the easiest thing to get subtly wrong in any migration, and a 30-second dig check beats debugging it after the router switch.
Step 5: switch your router’s DNS
Once validation looks right, set your router’s DHCP DNS server to the EliHole host’s IP. Devices pick up the new resolver as their DHCP leases renew, and traffic shifts from Pi-hole to EliHole gradually rather than all at once.
Keep Pi-hole running for a few days as a safety net. When the EliHole query log shows your whole network’s traffic and nothing is misbehaving, decommission Pi-hole: stop the service, and reclaim the host or repurpose it — a natural candidate is a second EliHole instance as a clustered slave (see below).
What doesn’t transfer
Two things are skipped, and the import report tells you about both:
- Clients — Pi-hole’s per-client records don’t map to anything in EliHole.
- Groups — EliHole has no client-group feature yet, so group assignments and group-scoped rules have nowhere to land.
The practical consequence: any rule that was scoped to a group in Pi-hole arrives in EliHole as a global rule (or not at all, if it only existed through group membership — the report shows you which). If your setup depends on per-client policies — say, stricter blocking for the kids’ devices and a permissive profile for your work laptop — that segmentation does not survive the migration today. Review the imported lists with that in mind before flipping the router, and either accept network-wide rules or hold off until client groups land in EliHole.
For most single-policy home networks, nothing changes: the blocklists, whitelists, and adlists behave exactly as they did.
After the switch
Migration is also a chance to pick up what Pi-hole couldn’t give you. DoH works out of the box at /dns-query, DoT needs only a certificate, and Prometheus can scrape /metrics immediately. And if you previously ran Gravity Sync to keep two Pi-holes aligned, EliHole’s native master-slave clustering replaces that entire setup — relevant now that Gravity Sync is archived and HA needs a new answer.