Skip to main content

📅 Using date rules

Background information​

Goal of the date rules​

Most images have metadata for dates, but these are split in multiple places and around 10-20% of "real world" photos have incomplete data metadata. The configurable date time parser allows us to get these dates and display them nicely as the user wants it too.

How does it work?​

The logic for extracting local time is described as a list of rules that should be applied one after another until one rule is able to extract date time (or until all rules are tried without success).

If a rule can't fetch the time (e.g. the EXIF tag value is not present or the path doesn't match the rule) then that rule is considered to be not applicable.

Dates you set by hand​

A date you set by hand in a photo's info panel, or for many photos at once with Change date and time…, is not a rule: it always wins over every rule in the list, on every scan and rescan, however you order or edit your rules. The info panel says Set by you under such a date. To hand the photo back to the rules, open it, edit its date and click Remove timestamp; the rules then decide its date again, so the photo keeps a date read from its file if it has one. New in 1.4.0 Up to version 1.3.0 a hand-set date only applied through a rule called Timestamp set by user, and it stopped sticking once that rule was deleted or moved below another; that rule is gone from every saved list after the update.

Figuring out the timezone​

Some sources of data might give us very rich information, e.g. timestamp + timezone, but others only allow getting local time (without knowing real timestamp).

For historical reasons, it is expected to have a timestamp and a timezone.

In some cases, it is known that the local time the rule would obtain is not in the desired timezone. E.g. video date time tag QuickTime:CreateDate is by standard written in UTC rather than local time. For such cases, each rule can optionally have setting "transform_tz" set to "1" - in that case this rule should also specify "source_tz" and "report_tz" settings where "source_tz" is describing the timezone that the rule is getting and "report_tz" is describing the timezone of the location where the photo/video was taken. Both "source_tz" and "report_tz" should be one of the following:

  • "utc" - UTC timezone
  • "gps_timezonefinder" - the timezone of the GPS location associated with the photo/video
  • "user_default" - the Default timezone set in your user settings; several of the built-in rules rely on this, including "Video creation datetime in user default timezone"
  • "server_local" - the local timezone of the machine running LibrePhotos (in Docker this is normally UTC unless you set a TZ for the container)
  • "name:<timezone_name>" - the timezone with the name <timezone_name>, e.g. "name:Europe/Berlin"

The predefined rules use "utc" for "source_tz" and "gps_timezonefinder" or "user_default" for "report_tz". New in 1.5.0 A rule you write yourself (see Writing your own rules) can also convert to a time zone you pick; "server_local" only works in a rule list saved through the API (the datetime_rules of your user). Up to 1.4.0 the settings page could not change a rule at all.

If either "source_tz" or "report_tz" could not be obtained, the rule is considered to be not applicable.

Videos​

Videos keep their date in other tags than photos, and the default rules read three of them:

  • Phone videos (iPhone, many Android phones) state the local time they were recorded at, with its UTC offset, in QuickTime:CreationDate. The rule "Local time from the video's QuickTime:CreationDate tag (phones)" uses that time as is, so no time zone has to be guessed. It is ranked above the rules that convert the UTC QuickTime:CreateDate.
  • Other MP4 and MOV files only have the UTC QuickTime:CreateDate, converted with the time zone of the video's position or, without one, your default time zone.
  • MKV and WebM files have a UTC Matroska:DateTimeOriginal, converted the same way by the two "MKV/WebM creation date" rules.

New in 1.4.0 After the update, accounts whose rules still contain both "Get Video creation tag in UTC + figure out timezone using GPS coordinates" (ID 2) and "Video creation datetime in user default timezone" (ID 4) get the three new rules (IDs 17, 18 and 19) next to them; a list without either of those two is left as you set it, and Reset To Defaults adds them. Videos already in your library get the new dates with Apply date rules to existing photos or a Rescan.

What gets stored, and why times are not converted for you​

Once a rule succeeds, LibrePhotos stores the local time the camera recorded — the time you would have read off the camera when you took the shot.

This is deliberate. A photo taken at 14:00 in Tokyo and one taken at 14:00 in Berlin are both shown as 14:00, because that is the time each one was actually taken. LibrePhotos does not re-cast your library into the timezone you happen to be browsing from; if it did, every photo would shift whenever you travelled, and photos from a holiday abroad would no longer line up with the day you remember them on.

New in 1.5.0 Next to the local time, LibrePhotos stores its UTC offset when the rule that read it knows one: the offset written after the time (2024:04:03 03:00:00-07:00), else the offset tag that goes with the date tag (EXIF:OffsetTimeOriginal for EXIF:DateTimeOriginal and XMP:DateCreated, EXIF:OffsetTime for EXIF:ModifyDate), or for a rule that converts a UTC time the offset of the time zone it converted to, on that day. The info panel shows it after the time, for example "Sunday, 23:30 (UTC-07:00)". A date read from a file name or a file's modified time, and a date you set by hand, have no offset. Photos already in your library get it with Apply date rules to existing photos or a Rescan.

note

Under the hood the local time is tagged as UTC before it is saved. That is an internal storage detail, not a claim that the photo was taken in UTC — it is what keeps the wall-clock time stable for every viewer. If you query the database directly, read the timestamps as-is and do not convert them.

The different rule types​

Currently, supported rule types:

  • "exif" - local time is taken using exif tag params["exif_tag"] as obtained with exiftool. An XMP sidecar next to the photo wins over the file (see Which sidecars are read). For EXIF:DateTimeOriginal and Composite:GPSDateTime the sidecar is also read under its XMP name (exif:DateTimeOriginal, exif:GPSTimeStamp); any other EXIF tag in a rule is not looked up in the sidecar, so to use a property that only a sidecar holds, name its XMP tag directly (for example XMP:<tag>). XMP:DateCreated, where LibrePhotos writes the dates you set when Write edits to files is on, is the first rule of the default list. Accounts created before 1.1.0 do not have that rule unless they add it with Add Rule or Reset To Defaults. New in 1.5.0 These date tags hold local time: XMP:DateCreated, EXIF:DateTimeOriginal, EXIF:ModifyDate and QuickTime:CreationDate. Some apps still write them in UTC, with a trailing Z (2025:06:02 06:30:00Z); such a value is turned into local time with the date's offset tag (see above), else the time zone of the photo's position, else your default time zone. Up to 1.4.0 the Z was ignored, so such a photo was off by its UTC offset and could land on another day; apply the rules again to fix the photos already in your library. A rule with "transform_tz" says itself which zone its tag is in and is not changed by this.
  • "path" - time is taken from the filename using a regular expression matching. With "path_part" set to "full_path" the whole path is searched instead of the file name. New in 1.5.0 A rule you write yourself names where the date is with a "date_pattern" such as YYYY-MM-DD HH.mm.ss (see Writing your own rules). An older rule saved through the API with its own regular expression ("custom_regexp") keeps working, but a new or changed rule cannot set one any more.
  • "filesystem" - time is taken from a file property. params["file_property"] must be "mtime" (file modified time) or "ctime" (file created time). Since these are UNIX timestamps without timezones they are always translated to local time using UTC.
  • "takeout_json" - the capture time in the Google Takeout JSON next to the file (photoTakenTime). It is a UTC timestamp, so the predefined rules convert it to the time zone of the photo's position (ID 20) or to your default time zone (ID 21). They sit right before the file name rule. See Importing a Google Takeout export. New in 1.4.0 After the update, an account whose rule list is still a default list (default rules only, in the default order) gets both rules before the file name rule; a list you changed is left as it is.
  • "user_defined" - the old Timestamp set by user rule. It no longer matches anything, since a date you set by hand always wins (see above), and the settings page no longer offers it.

How to use it​

Adding optional rules​

To add a new rule, go to settings and navigate to the date time parsing rules. Click on the Add Rule button. You can now add optional rules, such as using the file's modified or created time.

To remove a rule again, click the X (Delete rule) at the right-hand end of its row. The Reset To Defaults button next to Add Rule puts the list back to the rules LibrePhotos ships with; it is greyed out while your list already matches the default rules in their default order.

Writing your own rules​

New in 1.5.0 When no predefined rule reads your files' dates, write your own. Click New Rule next to Add Rule, or Duplicate and edit (the copy icon) on a predefined rule to start from it. A rule you wrote has an Edit rule pencil instead; the predefined rules stay as they are. In the form:

  • Read the date from: a Metadata tag, the File name or the File time.
  • Tag: one of the date tags LibrePhotos can read, such as EXIF:CreateDate, QuickTime:MediaCreateDate or Composite:SubSecDateTimeOriginal. Tags that usually hold the time in UTC say so. Other tags cannot be picked: a tag name ExifTool does not know reads nothing, and a rule on it would never apply.
  • Where the date is (file name): anywhere in the name, a WhatsApp name, or My own pattern, written with YYYY (year), MM (month), DD (day), HH (hour), mm (minute), ss (second) and ? (any one character); every other character stands for itself. For files named 2023-01-01 12.00.00 (2).jpg that is YYYY-MM-DD HH.mm.ss, and DD.MM.YYYY reads a day-first date. The year, month and day are required. Try it on a file name shows the date the pattern reads. Match the full path searches the folders too, for example YYYY/MM/DD.
  • Time zone: As recorded keeps the time as the local time it is, Recorded in UTC converts it to the time zone at the photo's location, your default time zone or one you pick.
  • Only when...: apply the rule only when the folder path, the file name or a tag (the camera model, for example) contains a text.
  • Name: filled in from your choices until you write your own.

Save Rule checks the rule with the server first and shows anything it refuses next to the field; the rule is then added at the end of the list. Like every change to the list, it is stored once you confirm Save changes?, and photos already in your library get its dates with Apply date rules to existing photos.

Seeing why a photo has its date​

New in 1.5.0 Open a photo of yours and click Why this date? under its date in the info panel. It lists every saved rule in order with what it reads from that photo (a date, Does not apply, or why it cannot run), and marks the one a scan takes the date from with Used. It also says when the photo shows another date now, which applying the rules or a rescan would change, and when the date was set by hand, which wins over every rule. Nothing is changed; save the rules first to test a change.

Changing the order​

The top rules are applied first and the bottom rules last. To change the order, drag and drop the rules. Adding, deleting, reordering and resetting rules only take effect once you save your settings — LibrePhotos prompts you with Save changes? and you confirm by clicking Update.

Applying the rules​

The date rules are applied on each scan, so photos scanned after a change use the new rules. New in 1.4.0 To apply them to the photos already in your library, use Apply date rules to existing photos.

  • Right after you save changed rules, the date rules card shows Your date rules changed with an Apply to existing photos button.
  • At any time, open the Library page (from the profile menu in the top-right corner, choose Library; or press Ctrl+K and search for "Library") and click Apply in the Dates section.

Both start the same background job, Apply Date Rules. It reads the date of every photo again with your current rules and moves each photo whose date changed to its new day. It does nothing else: no thumbnails, faces or other metadata are redone, and nothing is written to your files. A date you set by hand is never changed. When it is done, a message says how many photos moved to another day and how many keep the date you set by hand; the job list has the photos whose date could not be read. Event albums are not rebuilt by it: click Generate under Generate Event Albums on the Library page afterwards so your events follow the new dates.

Up to version 1.3.0 the only way was a full Rescan: in the Scan Library section, click the arrow next to the Scan button and choose Rescan (or Rescan All Photos in the command palette). It still works, but re-processes every file, which takes much longer. A plain Scan does not apply changed rules to photos it has seen before: it only looks at files that are new or changed since the last scan.

Troubleshooting​

Every photo is off by the same number of hours.

If your whole library is shifted by a constant amount — and that amount happens to match your own UTC offset — no date rule will fix it, because the rules are not what is wrong. This was a display bug: the times were stored correctly, but the web interface converted them into the timezone of the browser you were viewing from, so a viewer at UTC+3 saw every photo three hours late. It is fixed in current versions; update and reload the page, and the stored times will show as they always were. No rescan is needed.

A rule change had no effect at all.

Check that you applied the rules to the photos already in your library with Apply date rules to existing photos or Rescan, not a normal scan (see above), and that the rule you expect to win is above the one currently matching — the first rule that can produce a time is the one that is used. A rule that names an EXIF tag your files do not carry is silently skipped, so it is worth confirming the tag actually exists in your photos: Why this date? on one of them shows what each rule reads.

One particular photo ignores every rule.

If you once corrected that photo's date by hand, LibrePhotos remembered it, and a date set by hand wins over every rule (the info panel shows Set by you under it). To hand the photo back to the rules, open it, edit its date and click Remove timestamp.