Home Assistant History Exporter

Keep your own copy of your Home Assistant history.

Home Assistant keeps the detailed history of your devices for 10 days, unless you changed that setting, and then deletes it. The History Exporter saves that history to your computer, one day at a time, as ordinary files that stay yours for as long as you keep them. It runs on your computer, only reads from Home Assistant, and changes nothing there.

Features

• Back up your whole history: every recorded change of every entity, with its attributes, including entities that are unavailable at the moment.
• Your choice of file format: JSONL, CSV and Parquet, one or several at once, with identical content.
• Complete days: each export covers a full calendar day in your time zone, including the days the clocks change.
• Safe to repeat: days you already saved are skipped, so you can run it every day, by hand or automatically.
• No half-finished days: a day is saved completely or not at all, even after a crash or a power cut.
• Checks its own work: every file is read back before a day counts as saved, and hhe verify confirms later that your files are still intact.
• See what you have: hhe status lists your saved days and any gaps.
• Add a format later: hhe convert creates another format from the days you saved, without contacting Home Assistant.
• Private: no cloud service, no add-on and no integration. Your history goes from your Home Assistant to your own disk and nowhere else.

What you need

• A computer with Windows, macOS or Linux that can reach your Home Assistant. If you can open Home Assistant in a browser on that computer, it can. Exports run on this computer, so it needs to be switched on for them.
• Python 3.12 or newer and pipx. Python runs the History Exporter, and pipx installs it. Installation covers both.
• A long-lived access token, a kind of password that lets the History Exporter read from your Home Assistant. The Quickstart shows you how to create one.
• Disk space. One exported day of a large home can reach several hundred MB as JSONL. Parquet needs much less.

Installation

If you already have pipx, this is all you need:

pipx install ha-history-exporter

Otherwise, open the guide for your computer below. It starts from the beginning. Run one command at a time, in the order shown.

Parquet support

Parquet files need one more component. JSONL and CSV work without it.

pipx inject ha-history-exporter pyarrow

This component is not available for Windows on ARM processors or for 32-bit ARM systems such as a 32-bit Raspberry Pi OS. Use JSONL or CSV there.

Updating

pipx upgrade ha-history-exporter

Quickstart

1. Create an access token

In Home Assistant:

1. Open your profile: select your name at the bottom of the sidebar.
2. Open Security and scroll down to Long-lived access tokens.
3. Select Create token and give it a name, such as History Exporter.
4. Copy the token right away. Home Assistant shows it only once.

2. Run the setup

hhe init

The setup asks a few questions. Press Enter to accept the suggestion shown in square brackets.

After the token, the setup connects to your Home Assistant and shows OK: Home Assistant with your version and number of entities. If it reports a problem, answer n, look it up under Troubleshooting and run hhe init again.

Check the retention before you answer. Open your configuration.yaml in Home Assistant and look for purge_keep_days under recorder:. If it is not there, the value is 10. Enter the real number: with a number that is too high, days Home Assistant has already deleted are saved empty or incomplete, and they count as done.

3. Save your first backup

This saves every complete day Home Assistant still has, if it keeps 10 days of history:

hhe export --last-days 9

The right number is always one less than your retention, because Home Assistant is already deleting the oldest day. With purge_keep_days: 30, use --last-days 29. If the number is too high, the export saves the days it can, names the days it skipped and ends with exit code 1.

The export pauses between its requests to keep your Home Assistant responsive, so this can take a while. At the end, you see one line for each day:

2026-06-13  ok       184213 state objects
2026-06-14  ok       179846 state objects

4. Find your files

Your history is in the ha-history-exports folder in your home folder, unless you chose another one. This command lists the days you have:

hhe status

To keep your archive growing, run hhe export regularly or set up daily exports. Without further options, it saves yesterday.

Everyday commands

Configuration

hhe init stores your settings. You can change them at any time.

These commands help you look at your settings:

Where your files are

If your Home Assistant slows down during an export

The default settings suit a home with about 1400 entities. If Home Assistant feels slow during an export, ask for fewer entities at a time and pause longer:

hhe config set requests.batch_size 10

hhe config set requests.sleep_between_requests 1.5

hhe config set homeassistant.token --stdin < token.txt

Get-Content token.txt | hhe config set homeassistant.token --stdin

Output

ha-history-exports/
  exports/daily/2026/06/
    2026-06-15.jsonl            the history of this day
    2026-06-15.csv
    2026-06-15.parquet
    2026-06-15.manifest.json    the record of this day
  metadata/                     your entities at each export, and a list of exported days
  logs/                         a log file for each run
  hhe-archive.json              the time zone of this archive

You get the formats you chose. To back up your archive, copy the whole ha-history-exports folder.

Formats

All formats hold the same content.

Each entry has these fields:

A JSONL line looks like this, on one line in the file:

{"entity_id": "sensor.kitchen_temperature", "state": "21.5",
 "last_changed": "2026-06-15T06:30:00+00:00",
 "last_updated": "2026-06-15T06:30:00+00:00",
 "attributes": {"unit_of_measurement": "°C"},
 "local_offset": "+02:00"}

This DuckDB query reads one sensor from all your Parquet files:

SELECT entity_id, state, last_changed
FROM read_parquet('~/ha-history-exports/exports/daily/**/*.parquet')
WHERE entity_id = 'sensor.kitchen_temperature'
ORDER BY last_changed;

The record of each day

The .manifest.json file records what was saved for a day, with checksums of its files. Keep it with your files: hhe verify needs it.

A day with a successful record counts as saved, even if you later move or delete its files. hhe verify then reports those files as missing, so you can keep older days on other storage.

Day status

hhe status shows each day as one of these:

File check

hhe verify reports each file as one of these:

Time zone of an archive

All days in an archive use the same time zone, the one set when the archive was created. To use another time zone, save to a different folder.

Exit codes

Every command reports how it ended with an exit code. You only need these for scripts and scheduled tasks. Add --json to hhe export, convert, verify, status or doctor to get the result in a form that programs can read.

If one day fails, the export continues with the next day. A day outside your retention is skipped, and the export saves the other days. A rejected token, an unreachable Home Assistant, a certificate problem or an internal error ends the run.

Automating daily exports

This command, run once a day, keeps your archive complete. It covers two days, so a single missed run does no harm, and it skips days you already saved:

hhe export --last-days 2

If your computer is often off for several days, use a larger number, up to one less than your retention. A scheduled export needs no input, because your token is stored.

Troubleshooting

Run hhe doctor first. It checks your installation, settings, saved files and connection, and for most problems it shows the command that fixes them.

hhe or pipx is not recognized, or command not found. Close the terminal and open a new one. This includes terminals inside other programs such as VS Code, which need a restart of the program. If that does not help, run py -m pipx ensurepath on Windows or pipx ensurepath on macOS and Linux, and open a new terminal again.

py is not recognized on Windows. Open a new PowerShell window. If that does not help, search the Start menu for Manage app execution aliases and check that the entries for Python are on.

pipx reports that the History Exporter needs a newer Python. It needs Python 3.12 or newer. See the guide for your computer under Installation.

No Home Assistant URL is configured. or No Home Assistant access token is configured. Run hhe init.

… is not a valid Home Assistant base URL. Enter only the start of the address: http:// or https://, the host name and the port. For example, use http://homeassistant.local:8123, without anything after the port, such as /lovelace/0.

Home Assistant rejected the access token (HTTP 401). The token is wrong or was deleted. Create a new one as in the Quickstart and store it:

hhe config set homeassistant.token

Home Assistant is not available at … Check that the address works in a browser on this computer. If homeassistant.local does not work, use the IP address of your Home Assistant instead, for example http://<your-ip-address>:8123. If this computer uses a proxy, exclude that address from it.

Home Assistant did not answer in time. Give each request more time and ask for fewer entities at once:

hhe export --timeout 300 --batch-size 5

Home Assistant could not answer …: redirected with HTTP 301. The address forwards to another one, often from http:// to https://. Use the address your browser ends up on:

hhe config set homeassistant.url https://homeassistant.example.net

The HTTPS certificate of Home Assistant could not be verified. If you use a certificate from your own certificate authority, point the History Exporter to that authority:

hhe config set homeassistant.ca_bundle <path-to-ca.pem>

… is reached over plain HTTP outside the local network … Your access token travels unencrypted. Use the https:// address of your Home Assistant.

Skipped … day(s) outside the …-day Recorder retention These days are too old. Home Assistant may already have deleted part of their history, so the export leaves them out. It saves all other days and ends with exit code 1. A day that is already saved stays as it is, even with --force.

Ask for fewer days: at most one less than your retention. This also applies to a scheduled export, which ends with exit code 1 for as long as such a day is in its range. If the number in the message is not your retention, correct it, with your own number in place of 30:

hhe config set recorder.purge_keep_days 30

Empty history … cannot be verified without Recorder retention. Store the retention of your Home Assistant, with your own number in place of 10:

hhe config set recorder.purge_keep_days 10

Parquet output is enabled but pyarrow is not installed. Follow Parquet support, or save JSONL instead:

hhe config set export.formats jsonl

export.timezone is …, but this archive's days are in … Remove the time zone setting, or save to a different folder:

hhe config unset export.timezone

Unknown configuration key '…' The name is misspelled. The message suggests a similar valid name if there is one, and hhe config list shows them all.

Another export is already running for this output directory. Wait until that run has finished, then start again.

A day shows as failed. Run the same export again. Days that failed are not skipped. The log file named at the end of the run has the details.

hhe verify reports unexpected files. A file for that day is in the folder, but its record does not name it. Check the file, then move or delete it.

If none of this helps, please open a GitHub issue and include:

• the version, from hhe --version;
• your operating system;
• the exact error message;
• the output of hhe doctor, without private addresses.

Known limitations

• Older days cannot be recovered. The History Exporter can only save what Home Assistant still has, so start early and export regularly.
• Long-term statistics are not exported. Home Assistant keeps these separate hourly summaries of sensors beyond the retention, and they are not part of the history the History Exporter reads.
• Only entities that exist at the time of the export are saved. The history of an entity you deleted is not included.
• Only recorded entities are saved. An entity you excluded from the Recorder in Home Assistant has no history to export.
• Spreadsheets can misread CSV files. They treat a cell that starts with =, +, - or @ as a formula. Import CSV files as text, or use JSONL or Parquet for analysis.
• Network drives depend on their server. Let only one computer at a time write to an archive there.

Security

• The History Exporter only reads from Home Assistant and changes nothing there.
• Your access token is stored in credentials.toml, which only your account can read. It never appears in an export, a log or an error message.
• The token goes only to the address you configured. The History Exporter verifies HTTPS certificates and does not follow redirects.
• Your exports, entity lists and logs describe what happens in your home. Treat them as private, and check a log file before you share it: it lists entity names and, after an internal error, technical details.

To report a vulnerability, see the security policy.

Links

• Releases: every version, with its notes
• PyPI: the package page
• Issues: questions, setups and ideas
• Discord: the same, as a conversation
• License (MIT)
• Elsewhere: GitHub, YouTube, and Instagram