Frigate recording retention: continuous, motion and alerts, and how big a disk you need

Recording is the easy part of a Frigate NVR to switch on and the hard part to size. Without a plan, one of two things happens. Either retention is set to "30 days of everything" and the disk fills in a week, at which point Frigate starts deleting the oldest footage on its own; or retention is so short that the clip you needed from last Tuesday is already gone. A retention plan is a short calculation and a few numbers in config.yml. This post walks through both.

What Frigate keeps

Frigate records in short segments and keeps three kinds of footage, each with its own retention:

• Continuous: all video, whether or not anything moved.
• Motion: only segments in which motion was detected.
• Alerts and detections: segments that overlap a review item, with a few seconds before and after (pre_capture and post_capture, both 5 seconds by default).

Each kind has its own number of days. A segment that overlaps an alert is the one you most want to keep, so give alerts the most days. Retention for alerts and detections also has a mode:

Three plans from the documentation

Frigate's recording documentation gives three starting points. Pick the one that matches what you would need after an incident.

Keep everything for a while. All video for 3 days, motion for 7 days, and anything overlapping an alert or detection for 30 days:

record:
  enabled: true
  continuous:
    days: 3
  motion:
    days: 7
  alerts:
    retain:
      days: 30
      mode: all
  detections:
    retain:
      days: 30
      mode: all

Reduced storage. No continuous retention; motion for 3 days; alerts and detections for 30 days, keeping only their segments with motion:

record:
  enabled: true
  motion:
    days: 3
  alerts:
    retain:
      days: 30
      mode: motion
  detections:
    retain:
      days: 30
      mode: motion

Alerts only. Video is discarded unless an alert is ongoing; alerts are kept for 30 days:

record:
  enabled: true
  continuous:
    days: 0
  alerts:
    retain:
      days: 30
      mode: motion

Continuous footage is what answers "what happened in the driveway at 3 a.m." when nothing was detected, which is why the first plan is a good default if the disk allows it. Retention values can be set globally, as above, and overridden per camera. Days may be decimals, so 0.5 keeps twelve hours.

Storage arithmetic

The disk you need depends on the bitrate of each camera's main stream and the plan you picked. The upper bound is continuous recording:

GB per day per camera = bitrate (Mbit/s) x 86,400 / 8 / 1,000

  2 Mbit/s  ->  21.6 GB/day
  4 Mbit/s  ->  43.2 GB/day
  6 Mbit/s  ->  64.8 GB/day
  8 Mbit/s  ->  86.4 GB/day

For the first plan, estimate each layer separately and add them. Continuous days are the full rate. Motion days and alert days are a fraction of it, and that fraction depends entirely on the scene: a camera on a quiet back garden may see motion a small part of the day, one facing a street much more. A worked example, arithmetic only:

4 cameras at 4 Mbit/s

Continuous, 3 days:      4 x 43.2 GB x 3          = 518 GB
Motion days 4-7:         4 x 43.2 GB x 4 x 0.20   = 138 GB   (assume 20% motion)
Alerts/detections 8-30:  4 x 43.2 GB x 23 x 0.05  = 199 GB   (assume 5% activity)
                                           Total  ~ 855 GB  -> plan for a 2 TB disk

The 20 and 5 percent figures are assumptions to replace with your own. After a few days, open System > Storage in Frigate: it shows how much space each camera's recordings use, which gives you a real per-day figure. That page counts Frigate's recordings only; for the disk itself, use df -h on the host.

Leave at least 20 percent of the disk free in the plan. Bitrates rise at night and in rain, cameras get added, and the emergency cleanup below works from the disk's real free space.

When the disk fills anyway

Frigate watches the free space of the disk holding /media/frigate/recordings. When less than roughly one hour of recording space remains, estimated from the current bitrate, it deletes the oldest recordings first, regardless of your retention settings, and logs a message. Two consequences follow:

• Anything else filling that disk, even files that are not Frigate's, can trigger deletion of your oldest recordings. Keep the recordings disk for recordings only.
• Frequent emergency cleanups mean your retention is larger than the disk. Reduce the days until normal retention keeps up.

Also check from inside the container that /media/frigate really is the disk you think it is:

docker exec frigate df -h /media/frigate

If a disk or NFS share is not actually mounted there, Frigate fills whatever filesystem is underneath, usually the system disk. If you record to a NAS, a dedicated dataset with its own quota keeps a runaway Frigate from filling the rest of the NAS, and keeps the NAS's other files from triggering Frigate's cleanup.

Snapshots and exports

Snapshots are still images of tracked objects. They are what Home Assistant attaches to notifications, and they are off by default. Turn them on and give them their own retention:

snapshots:
  enabled: true
  bounding_box: true
  retain:
    default: 30

Exports are how you keep a specific clip beyond retention. Use the Export button in the History view (or right-click a review item), choose the time range and give it a name. Exports are saved separately and are not removed by retention. Download an export to hand a clip to someone instead of copying files out of the recordings folder.

H.265 recordings on Apple devices

If a camera records an H.265 main stream, Safari on macOS and iPhone may refuse to play its recordings. Frigate has a per-camera setting for this:

cameras:
  driveway:
    ffmpeg:
      apple_compatibility: true

Test playback from every device that will view recordings, including the Home Assistant app, before you rely on it.

What to back up

The recordings themselves are rarely backed up: they are large, they expire by design, and the important clips are exports. What you must back up is small:

• config.yml (your whole configuration)
• frigate.db (review items, tracked objects, users), copied while Frigate is stopped or with SQLite's backup command
• your compose.yaml and .env
• the exports you want to keep, copied off the Frigate disk

If Frigate runs in a Proxmox VM, a VM backup covers all of it. Untick Backup on the recordings disk in the VM's Hardware tab so the backup skips the footage.

Checklist

• Plan chosen and written down: continuous, motion and alert/detection days.
• Storage estimate done with your real bitrates, plus 20 percent headroom.
• The record block in config.yml matches the plan.
• Snapshots enabled with retention.
• The recordings disk holds nothing but Frigate media.
• docker exec frigate df -h /media/frigate shows the right disk.
• Storage page checked after a week, retention adjusted.
• Config, database and compose files are in your backups.

Found this useful? Subscribe on YouTube for the daily video, or follow the RSS feed.