2025.10.1
Home ▸ Integrations ▸

File

The File integration allows storing notifications in a file or setting up a sensor based on a file’s content.

This integration is enabled by default, unless you’ve disabled or removed the default_config: line from your configuration. If that is the case, the following example shows you how to enable this integration manually:

# Basic configuration.yaml entry
file:

Configuration

To add the File integration to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

Action: Read file

The file.read_file action reads a file and returns the data in a response.

Data attribute Optional Description
file_name No The path of the file and name to read. Files should be UTF-8 encoded. Example: config/www/myfile.yaml
file_encoding No The content type of the file (JSON or YAML). Example: YAML

Note: The file paths should be relative to the Home Assistant configuration directory.

Note: File paths must be added to allowlist_external_dirs in your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more].

The action returns a dictionary with a data element containing the parsed content from the file.

Example, read a JSON file out of the www directory.

  - action: file.read_file
    data:
      file_name: config/www/myfile.json
      file_encoding: JSON
    response_variable: file_content

Contents of myfile.json

{
  "latitude": 32.87336,
  "longitude": -117.22743,
  "gps_accuracy": 1.2
}

Response:

data:
  latitude: 32.87336
  longitude: -117.22743
  gps_accuracy: 1.2

Notifications

Make sure that the file you want to use is added to the allowlist_external_dirs. The file will be created if it doesn’t exist, but make sure the folder exists. Add the path of your configuration folder (for example, /config/file_notifications) to save the file there. Setting timestamp to true adds a timestamp to every logged entry. After creating a config entry, you can change the entry name, the name of the notify entity, or the entity ID, if you prefer.

To use notifications in automations or scripts, see the getting started with automation page.

Use the notify.send_message action to store notification messages.

Sensor

The file sensor platform reads the entries from a plain-text file and shows the found value. Only the last line of the file is used. This is similar to do $ tail -n 1 sensor.txt on the command-line. Note that file paths must be added to allowlist_external_dirs.

Examples

In this section you find some real-life examples of how to use this sensor.

Entries as JSON

Assuming that the log file contains multiple values formatted as JSON as shown below:

[...]
{"temperature": 21, "humidity": 39}
{"temperature": 22, "humidity": 36}

This would require the following settings to extract the temperature:

  • Name: Temperature
  • File path: /config/sensor.json
  • Value template: {{ value_json.temperature }}
  • Unit of measurement: "°C"

Entries as CSV

Assuming the log file contains multiple values formatted as CSV as shown below:

timestamp,temperature,humidity
1631472948,21,39
1631472949,22,36

This would require the following settings to extract the temperature:

  • Name: Temperature
  • File path: /config/sensor.csv
  • Value template: {{ value.split(",")[1] }}
  • Unit of measurement: "°C"

Related topics