# pihole.toml changes do not take effect
**URL:** https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387
**Category:** Help
**Created:** [March 13, 2026, 8:52pm UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387 "2026-03-13T20:52:34Z")
**Posts on this page:** 10
**Page:** 1
### Author:  [@happyanimal55](https://discourse.pi-hole.net/u/happyanimal55)
#### Post date: [March 13, 2026, 8:52pm UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/1 "2026-03-13T20:52:34Z")
Objective: Configure local DNS records through a configuration file.
It is absolutely unacceptable to configure local DNS records through the Web UI.
It is absolutely unacceptable to configure local DNS records through the `pihole` CLI.
## Expected Behaviour:
I should be able to edit the configuration option `[dns]::hosts` in file `/etc/pihole/pihole.toml` and have my changes take place after `systemctl restart pihole-FTL`.
These instructions come from the `/etc/pihole/hosts/custom.list`
```auto
root@vox:/etc/pihole/hosts# head -n 23 custom.list
# Pi-hole: A black hole for Internet advertisements
# (c) 2026 Pi-hole, LLC (https://pi-hole.net)
# Network-wide ad blocking via your own hardware.
#
# Custom DNS entries (HOSTS file)
#
##################################################################################
# #
# FILE AUTOMATICALLY POPULATED BY PI-HOLE #
# ANY CHANGES MADE TO THIS FILE WILL BE LOST WHEN THE CONFIGURATION CHANGES #
# #
# IF YOU WISH TO CHANGE ANY OF THESE VALUES, CHANGE THEM IN #
# /etc/pihole/pihole.toml #
# and restart pihole-FTL #
# #
# ANY OTHER CHANGES SHOULD BE MADE IN A SEPARATE CONFIG FILE #
# WITHIN /etc/dnsmasq.d/yourname.conf #
# (make sure misc.etc_dnsmasq_d is set to true in /etc/pihole/pihole.toml) #
# #
# Last updated: 2026-03-13 14:59:53 CDT #
# by FTL version v6.5 #
# #
##################################################################################
root@vox:/etc/pihole/hosts#
```
- Operating System: Raspberry Pi Lite (Debian Trixie 13)
- Hardware: Raspberry Pi 5 1GB
- Docker compose file or Docker run command: N/A
- Docker engine version: N/A
## Actual Behaviour:
Nothing happens. As soon as I edit the file, FTL immediately overwrites the file with whatever was presently in there.
`systemctl stop pihole-FTL` followed by editing and `systemctl start pihole-FTL`immediately overwrites /etc/pihole/pihole.toml with what’s currently in there.
`printenv` on the root account shows no environment variables starting with `FTLCONF`
## Debug Token:
[✓] Your debug token is: [https://tricorder.pi-hole.net/4Eec3Xsz/](https://tricorder.pi-hole.net/4Eec3Xsz/)
---
### Author:  [@happyanimal55](https://discourse.pi-hole.net/u/happyanimal55)
#### Post date: [March 13, 2026, 8:59pm UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/2 "2026-03-13T20:59:13Z")
Further experimentation has revealed that
`systemctl start pihole-FTL` totally ignores the setting [misc]readOnly
---
### Author:  [@rdwebdesign](https://discourse.pi-hole.net/u/rdwebdesign)
#### Post date: [March 13, 2026, 8:59pm UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/3 "2026-03-13T20:59:26Z")
> [@happyanimal55](#):
>
> I should be able to edit the configuration option `[dns]::hosts` in file `/etc/pihole/pihole.toml`
You can, but you need to use the correct format when manually entering data in `pihole.toml`.
Are you sure you are using the correct format?
```auto
[dns]
hosts = ["127.0.0.1 mylocal", "192.168.0.1 therouter"]
```
Please check the documentation: [Configuration - Pi-hole documentation - dns.hosts](https://docs.pi-hole.net/ftldns/configfile/#hosts)
---
### Author:  [@happyanimal55](https://discourse.pi-hole.net/u/happyanimal55)
#### Post date: [March 13, 2026, 9:28pm UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/4 "2026-03-13T21:28:47Z")
Yes, I am certain I have formatted my toml correctly.
Some further experimental results
- PiHole’s TOML parser will strip blank lines, comments, and trailing commas from the `[dns]hosts` setting, even if the TOML is correctly formatted.
- If I paste invalid TOML into `[dns]hosts` pihole will reload the last-known good `[dns]hosts` setting
The issue was that I was pasting in comments and blank space and they’d all just disappear, making it look like I’d made 0 progress.
I’m surprised by how invalid TOML is handled. Is there a setting somewhere I can flip which makes everything crash and burn instead of reloading last known good?
---
### Author:  [@jfb](https://discourse.pi-hole.net/u/jfb)
#### Post date: [March 13, 2026, 9:47pm UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/6 "2026-03-13T21:47:37Z")
> [@happyanimal55](#):
>
> Objective: Configure local DNS records through a configuration file.
You can use the file _ **/etc/hosts** _ on the host OS. You don’t need to use either the Web UI or the pihole CLI. You can use any text editor you choose.
An example of a file on one of my Pi’s
```auto
cat /etc/hosts
127.0.0.1 localhost
::1 localhost ip6-localhost ip6-loopback
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters
127.0.1.1 Pi3BDev
192.168.0.1 TC-Extreme-3TB
192.168.0.2 TC-Extreme-3TB-extender
192.168.0.4 Printer
192.168.0.5 Airport-Express-PC
...
```
---
### Author:  [@robgill](https://discourse.pi-hole.net/u/robgill)
#### Post date: [March 14, 2026, 12:21am UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/8 "2026-03-14T00:21:32Z")
> [@happyanimal55](#):
>
> Is there a setting somewhere I can flip which makes everything crash and burn instead of reloading last known good?
I'm reasonably certain that this is not a good idea, but it is possible to prevent pihole overwriting your bespoke toml file.
Edits will need to be made, and the file set to immutable while the pihole-FTL service stopped. Once you are done editing, make the toml file [immutable using chattr](https://www.man7.org/linux/man-pages/man1/chattr.1.html) and then Pi-hole won't be able to delete, rewrite or overwrite it.
`sudo chattr +i /etc/pihole/pihole.toml`
Then restart the pihole-FTL service.
So long as the file is parseable, pihole will read the file and use it but won't overwrite your file. You will see a warning in FTL.log:
```auto
WARNING: Cannot move temporary config file to final location (Operation not permitted), content not updated.
```
If the file is not parseable, pihole will use its last known good config, but leave the mangled file alone:
```auto
ERROR: Cannot parse config file: (line 15) invalid value
ERROR: Cannot parse TOML file: (line 15) invalid value
INFO: Using config backup /etc/pihole/config_backups/pihole.toml.1
```
If you later wanted to change the file yourself, you would need to first remove the immutability flag:
`sudo chattr -i /etc/pihole/pihole.toml`
---
### Author:  [@rdwebdesign](https://discourse.pi-hole.net/u/rdwebdesign)
#### Post date: [March 14, 2026, 1:36am UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/9 "2026-03-14T01:36:55Z")
> [@happyanimal55](#):
>
> Is there a setting somewhere I can flip which makes everything crash and burn instead of reloading last known good?
No.
Pi-hole will always rewrite `pihole.toml` using only its own comments, which are part of the documentation.
Also, I don't know what will happen if you try to make the file immutable. This is not recommended.
* * *
If you really want to keep your comments, the only suggestion I have is: create your own `pihole.toml` file (with your settings and comments) and save it on your home directory.
Since you will never use the web interface or the CLI commands to change your settings, this file will contain all Pi-hole settings.
When you need to change something, you can edit this file and them copy it to `/etc/pihole/`.
---
### Author:  [@happyanimal55](https://discourse.pi-hole.net/u/happyanimal55)
#### Post date: [March 14, 2026, 2:25am UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/10 "2026-03-14T02:25:18Z")
> Pi-hole will always rewrite `pihole.toml` using only its own comments, which are part of the documentation.
Do you have a link I can follow? Maybe there are hidden developer docs somewhere I haven’t found and I would have wanted to read those before making the post.
- I didn’t see anything specifically in `pihole.toml`'s comments
- I couldn’t find a reference to this on docs.pi-hole.net: Almost all my information comes from the Docker \> Configuration page, and the Advanced \> Signals page seems to support the idea that pihole only reads from `pihole.toml` instead of overwriting it
- I also didn’t see anything in a brief search of the github repo, and I didn’t have enough time to actually read through the code.
Since I like to manage everything from one place where possible, I think I’ll utilize the /home/username/pihole.toml approach. I’ll always have the ability to `diff` my personal config and the live config – I just need to keep those autoformat rules in mind.
Thanks for the suggestions all, this is closable.
---
### Author:  [@rdwebdesign](https://discourse.pi-hole.net/u/rdwebdesign)
#### Post date: [March 14, 2026, 3:25am UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/11 "2026-03-14T03:25:24Z")
> [@happyanimal55](#):
>
> Do you have a link I can follow?
Link for what exactly? I'm not sure what you want to see.
If you don't believe me when I say the file is recreated, you can easily test yourself.
Create a backup copy of your `pihole.toml` and then delete the original file. You will see that the file is really gone.
Pi-hole will keep working without the file until you execute any operation that restarts the DNS resolver, like changing a config option via CLI or the web interface. You can test that executing `sudo pihole-FTL --config webserver.api.sessions 16`.
After that, the file `pihole.toml` will be back, because it was recreated by FTL.
EDIT:
I think I found what you are looking for.
This is a comment that explains `pihole.toml` is always rewritten after FTL parsing it:
>
And:
>
And the whole `toml_writer.c` file:
>
---
### Author:  [@system](https://discourse.pi-hole.net/u/system)
#### Post date: [April 4, 2026, 3:25am UTC](https://discourse.pi-hole.net/t/pihole-toml-changes-do-not-take-effect/85387/12 "2026-04-04T03:25:55Z")
This topic was automatically closed 21 days after the last reply. New replies are no longer allowed.