How to Edit Config.txt in Home Assistant

What config.txt does and why you might need to edit it

Config.txt is a plain text file that Home Assistant reads when it starts up. It holds settings that control how Home Assistant behaves — things like which port it listens on, how much detail it logs, and whether it runs in a specific mode. Most people never touch it because Home Assistant works fine with its built-in defaults. You edit config.txt only when you want to change something the web interface does not let you change, or when you are following instructions from a Home Assistant integration or add-on that specifically tells you to.

The file lives in your Home Assistant configuration directory. If you installed Home Assistant on a Raspberry Pi using the official image, that directory is /home/homeassistant/.homeassistant. If you used Docker, it is wherever you mounted your config volume. If you used a different installation method, the path varies — check your setup documentation.

Key Takeaways

Config.txt is a plain text file in your Home Assistant configuration directory that controls startup settings and logging behavior.
You can edit it using SSH (command line) or through the File Editor add-on if you have one installed, but never while Home Assistant is running.
After you save changes to config.txt, you must restart Home Assistant from the Settings menu for the changes to take effect.
If you make a syntax error in config.txt, Home Assistant will not start — keep a backup or know how to revert your changes.
Most Home Assistant customization happens in other files like automations.yaml or through the web interface, not in config.txt.

Accessing config.txt through SSH

SSH (find Shell) is a way to connect to your Home Assistant machine from another computer and run commands as if you were sitting at a terminal. This is the most direct way to edit config.txt, especially if you are already comfortable with command-line tools.

First, you need SSH access enabled. In Home Assistant, go to Settings → System → Termux add-on (or SSH add-on, depending on your installation). Install it if it is not already there, then start it. You will see a port number — usually 22. On your computer, open a terminal or command prompt and type ssh root@192.168.1.X -p 22, replacing 192.168.1.X with your Home Assistant machine's IP address. You will be prompted for a password — use the one you set in the add-on settings.

Once you are logged in, navigate to the config directory with cd /home/homeassistant/.homeassistant (or wherever your config lives). Then open config.txt with a text editor. The most common choices are nano or vi. Type nano config.txt to open it in nano, which is simpler for beginners. Make your changes, then press Ctrl+O to save, Enter to confirm the filename, and Ctrl+X to exit.

Using the File Editor add-on

If you do not want to use SSH, you can use the File Editor add-on, which gives you a text editor in your web browser. Go to Settings → Add-ons → Create New Add-on Repository (if needed) and search for "File Editor". Install it, then start it. Once it is running, you will see a new menu item in your sidebar called File Editor.

Click File Editor and you will see a file browser on the left. Navigate to your config directory and find config.txt. Click it to open it in the editor. Make your changes directly in the browser window. The editor usually auto-saves, but you can also press Ctrl+S to save manually. Unlike SSH, you do not need to restart anything — just close the editor when you are done.

The File Editor is slower than SSH for large files and does not give you the same command-line power, but it is much easier if you are not comfortable with terminals. The trade-off is that you are using a web interface instead of direct access to the file system.

Common settings you might edit in config.txt

Most config.txt changes fall into a few categories. Logging level controls how much detail Home Assistant writes to its logs. The default is INFO, which shows important events. You can change it to DEBUG for much more detail (useful when troubleshooting), or WARNING to see only serious problems. Add a line like logging: debug to enable debug logging.

HTTP port is the port Home Assistant listens on — usually 8123. If something else is using that port, you can change it by adding http: and then server_port: 8124 on the next line. Unit system controls whether temperatures show in Celsius or Fahrenheit, and distances in meters or miles. Add unit_system: us_customary for US units or unit_system: metric for metric.

You might also see instructions to add packages: to load additional configuration files, or homeassistant: settings to change your timezone or latitude and longitude. Always check the specific integration or add-on documentation before adding anything — the syntax must be exact, or Home Assistant will not start.

Why you must restart Home Assistant after editing

Home Assistant reads config.txt only when it starts up. If you edit the file while Home Assistant is running, the changes sit there doing nothing until you restart. Go to Settings → System → Restart Home Assistant and wait for it to come back online. You will see a notification when it is ready.

This is why it is important to get the syntax right before restarting. If you make a typo or forget a colon, Home Assistant may fail to start. If that happens, you will need to edit config.txt again (through SSH or by rebooting into recovery mode, depending on your setup) and fix the error. Keeping a backup of your config directory is a good habit.

Syntax rules and common mistakes

Config.txt uses YAML format, which is strict about spacing and structure. The most common mistakes are using tabs instead of spaces (YAML requires spaces), forgetting colons after keys, or indenting incorrectly. If you add a line like logging: debug, make sure there is a space after the colon and no extra spaces at the beginning of the line.

If you are adding a nested setting under a parent key, indent it with two spaces. For example, under http: you might add server_port: 8124 indented two spaces. If the indentation is wrong, Home Assistant will report a YAML error and refuse to start.

Before you restart, you can check your syntax by going to Settings → Developer Tools → YAML and pasting your config.txt content there. Home Assistant will tell you if there is a syntax error. This step can save you from a failed restart.

When not to edit config.txt

Most Home Assistant customization does not happen in config.txt. Automations, scripts, and scenes go in separate files or are created through the web interface. Device integrations are usually set up through Settings → Devices & Services, not by editing config.txt. If you are trying to add a new device or create an automation, look for a web interface option first.

Config.txt is for system-level settings that affect how Home Assistant itself runs. If you are not sure whether something belongs in config.txt, search the Home Assistant documentation or ask in the Home Assistant community forum. Editing the wrong file or adding settings in the wrong place is a common source of confusion.

Frequently Asked Questions

What happens if I edit config.txt while Home Assistant is running?

Nothing happens until you restart. Home Assistant only reads the file at startup. Your changes will sit in the file, ignored, until you go to Settings → System → Restart Home Assistant. Then the new settings take effect.

Can I break Home Assistant by editing config.txt wrong?

Yes. If you introduce a syntax error or an invalid setting, Home Assistant may fail to start. You will see an error in the logs. The fix is to edit config.txt again and correct the mistake, then restart. This is why keeping a backup of your config directory is wise.

Do I need to edit config.txt to add a new device or automation?

No. Most devices are added through Settings → Devices & Services in the web interface. Automations are created through Settings → Automations & Scenes or in a separate automations.yaml file. Config.txt is for system settings, not for adding integrations or automations.

Is SSH the only way to edit config.txt?

No. You can also use the File Editor add-on if you have it installed, which gives you a browser-based text editor. SSH is faster and more powerful, but File Editor is easier if you are not comfortable with command-line tools.

What should I do if Home Assistant will not start after I edited config.txt?

Connect via SSH and open config.txt again. Check the syntax carefully — look for missing colons, wrong indentation, or typos. You can also check the Home Assistant logs (usually in /home/homeassistant/.homeassistant/home-assistant.log) to see what error it reported. Fix the error and restart.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.